shopify_product_taxonomy 1.0.0

data/lib/product_taxonomy/models/serializers/value/dist/txt_serializer.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  module Serializers
+    module Value
+      module Dist
+        class TxtSerializer
+          class << self
+            def serialize_all(version:, locale: "en", padding: longest_gid_length)
+              header = <<~HEADER
+                # Shopify Product Taxonomy - Attribute Values: #{version}
+                # Format: {GID} : {Value name} [{Attribute name}]
+
+              HEADER
+
+              header + ProductTaxonomy::Value.all_values_sorted.map { serialize(_1, padding:, locale:) }.join("\n")
+            end
+
+            # @param value [Value]
+            # @param padding [Integer] The padding to use for the GID.
+            # @param locale [String] The locale to use for localization.
+            # @return [String]
+            def serialize(value, padding: 0, locale: "en")
+              "#{value.gid.ljust(padding)} : #{value.full_name(locale:)}"
+            end
+
+            private
+
+            def longest_gid_length
+              largest_id = ProductTaxonomy::Value.hashed_by(:id).keys.max
+              ProductTaxonomy::Value.find_by(id: largest_id).gid.length
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/product_taxonomy/models/taxonomy.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  class Taxonomy
+    attr_reader :verticals
+
+    def initialize(verticals:)
+      @verticals = verticals
+    end
+  end
+end

data/lib/product_taxonomy/models/value.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  # An attribute value in the product taxonomy. Referenced by a {ProductTaxonomy::Attribute}. For example, an
+  # attribute called "Color" could have values "Red", "Blue", and "Green".
+  class Value
+    include ActiveModel::Validations
+    include FormattedValidationErrors
+    extend Localized
+    extend Indexed
+
+    class << self
+      # Load values from source data. By default, this data is deserialized from a YAML file in the `data` directory.
+      #
+      # @param source_data [Array<Hash>] The source data to load values from.
+      def load_from_source(source_data)
+        raise ArgumentError, "source_data must be an array" unless source_data.is_a?(Array)
+
+        source_data.each do |value_data|
+          raise ArgumentError, "source_data must contain hashes" unless value_data.is_a?(Hash)
+
+          Value.create_validate_and_add!(
+            id: value_data["id"],
+            name: value_data["name"],
+            friendly_id: value_data["friendly_id"],
+            handle: value_data["handle"],
+          )
+        end
+      end
+
+      # Reset all class-level state
+      def reset
+        @localizations = nil
+        @hashed_models = nil
+      end
+
+      # Sort values by their localized name.
+      #
+      # @param values [Array<Value>] The values to sort.
+      # @param locale [String] The locale to sort by.
+      # @return [Array<Value>] The sorted values.
+      def sort_by_localized_name(values, locale: "en")
+        values.sort_by.with_index do |value, idx|
+          [
+            value.name(locale: "en").downcase == "other" ? 1 : 0,
+            *AlphanumericSorter.normalize_value(value.name(locale:)),
+            idx,
+          ]
+        end
+      end
+
+      # Sort values according to their English name, taking "other" into account.
+      #
+      # @param values [Array<Value>] The values to sort.
+      # @return [Array<Value>] The sorted values.
+      def all_values_sorted
+        all.sort_by do |value|
+          [
+            value.name(locale: "en").downcase == "other" ? 1 : 0,
+            value.name(locale: "en"),
+            value.id,
+          ]
+        end
+      end
+
+      # Get the next ID for a newly created value.
+      #
+      # @return [Integer] The next ID.
+      def next_id = (all.max_by(&:id)&.id || 0) + 1
+    end
+
+    # Validations that run when the value is created
+    validates :id, presence: true, numericality: { only_integer: true }, on: :create
+    validates :name, presence: true, on: :create
+    validates :friendly_id, presence: true, on: :create
+    validates :handle, presence: true, on: :create
+    validates_with ProductTaxonomy::Indexed::UniquenessValidator, attributes: [:friendly_id, :handle, :id], on: :create
+
+    # Validations that run when the taxonomy has been loaded
+    validate :friendly_id_prefix_resolves_to_attribute?, on: :taxonomy_loaded
+    validate :handle_prefix_matches_attribute?, on: :taxonomy_loaded
+
+    localized_attr_reader :name
+
+    attr_reader :id, :friendly_id, :handle
+
+    # @param id [Integer] The ID of the value.
+    # @param name [String] The name of the value.
+    # @param friendly_id [String] The friendly ID of the value.
+    # @param handle [String] The handle of the value.
+    def initialize(id:, name:, friendly_id:, handle:)
+      @id = id
+      @name = name
+      @friendly_id = friendly_id
+      @handle = handle
+    end
+
+    def gid
+      "gid://shopify/TaxonomyValue/#{id}"
+    end
+
+    # Get the primary attribute for this value.
+    #
+    # @return [ProductTaxonomy::Attribute] The primary attribute for this value.
+    def primary_attribute
+      @primary_attribute ||= Attribute.find_by(friendly_id: primary_attribute_friendly_id)
+    end
+
+    # Get the full name of the value, including the primary attribute.
+    #
+    # @param locale [String] The locale to get the name in.
+    # @return [String] The full name of the value.
+    def full_name(locale: "en")
+      "#{name(locale:)} [#{primary_attribute.name(locale:)}]"
+    end
+
+    private
+
+    def primary_attribute_friendly_id = friendly_id.split("__").first
+
+    #
+    # Validation
+    #
+    def friendly_id_prefix_resolves_to_attribute?
+      return if primary_attribute
+
+      errors.add(
+        :friendly_id,
+        :invalid_prefix,
+        message: "prefix \"#{primary_attribute_friendly_id}\" does not match the friendly_id of any attribute",
+      )
+    end
+
+    def handle_prefix_matches_attribute?
+      return if primary_attribute.nil?
+
+      handle_prefix = handle.split("__").first
+      return if primary_attribute && primary_attribute.handle == handle_prefix
+
+      errors.add(
+        :handle,
+        :invalid_prefix,
+        message: "prefix \"#{handle_prefix}\" does not match primary attribute handle \"#{primary_attribute.handle}\"",
+      )
+    end
+  end
+end

data/lib/product_taxonomy/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  VERSION = "1.0.0"
+end
+

data/lib/product_taxonomy.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "active_support/all"
+require "active_model"
+
+module ProductTaxonomy
+  DEFAULT_DATA_PATH = File.expand_path("../../data", __dir__)
+
+  class << self
+    attr_writer :data_path
+
+    def data_path
+      @data_path ||= DEFAULT_DATA_PATH
+    end
+  end
+end
+
+require_relative "product_taxonomy/version"
+require_relative "product_taxonomy/loader"
+require_relative "product_taxonomy/alphanumeric_sorter"
+require_relative "product_taxonomy/identifier_formatter"
+require_relative "product_taxonomy/localizations_validator"
+require_relative "product_taxonomy/models/mixins/localized"
+require_relative "product_taxonomy/models/mixins/indexed"
+require_relative "product_taxonomy/models/mixins/formatted_validation_errors"
+require_relative "product_taxonomy/models/attribute"
+require_relative "product_taxonomy/models/extended_attribute"
+require_relative "product_taxonomy/models/value"
+require_relative "product_taxonomy/models/category"
+require_relative "product_taxonomy/models/taxonomy"
+require_relative "product_taxonomy/models/mapping_rule"
+require_relative "product_taxonomy/models/integration_version"
+require_relative "product_taxonomy/models/serializers/category/data/data_serializer"
+require_relative "product_taxonomy/models/serializers/category/data/localizations_serializer"
+require_relative "product_taxonomy/models/serializers/category/data/full_names_serializer"
+require_relative "product_taxonomy/models/serializers/category/docs/siblings_serializer"
+require_relative "product_taxonomy/models/serializers/category/docs/search_serializer"
+require_relative "product_taxonomy/models/serializers/category/dist/json_serializer"
+require_relative "product_taxonomy/models/serializers/category/dist/txt_serializer"
+require_relative "product_taxonomy/models/serializers/attribute/data/data_serializer"
+require_relative "product_taxonomy/models/serializers/attribute/data/localizations_serializer"
+require_relative "product_taxonomy/models/serializers/attribute/docs/base_and_extended_serializer"
+require_relative "product_taxonomy/models/serializers/attribute/docs/reversed_serializer"
+require_relative "product_taxonomy/models/serializers/attribute/docs/search_serializer"
+require_relative "product_taxonomy/models/serializers/attribute/dist/json_serializer"
+require_relative "product_taxonomy/models/serializers/attribute/dist/txt_serializer"
+require_relative "product_taxonomy/models/serializers/value/data/data_serializer"
+require_relative "product_taxonomy/models/serializers/value/data/localizations_serializer"
+require_relative "product_taxonomy/models/serializers/value/dist/json_serializer"
+require_relative "product_taxonomy/models/serializers/value/dist/txt_serializer"

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification
+name: shopify_product_taxonomy
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Shopify
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-11-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.16.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.16.0
+description: A code-only gem providing Ruby classes and utilities to parse and process
+  Shopify's Standard Product Taxonomy data from YAML source files into an in-memory
+  Ruby object model. Data files are available at https://github.com/Shopify/product-taxonomy
+email:
+- gems@shopify.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/product_taxonomy.rb
+- lib/product_taxonomy/alphanumeric_sorter.rb
+- lib/product_taxonomy/identifier_formatter.rb
+- lib/product_taxonomy/loader.rb
+- lib/product_taxonomy/localizations_validator.rb
+- lib/product_taxonomy/models/attribute.rb
+- lib/product_taxonomy/models/category.rb
+- lib/product_taxonomy/models/extended_attribute.rb
+- lib/product_taxonomy/models/integration_version.rb
+- lib/product_taxonomy/models/mapping_rule.rb
+- lib/product_taxonomy/models/mixins/formatted_validation_errors.rb
+- lib/product_taxonomy/models/mixins/indexed.rb
+- lib/product_taxonomy/models/mixins/localized.rb
+- lib/product_taxonomy/models/serializers/attribute/data/data_serializer.rb
+- lib/product_taxonomy/models/serializers/attribute/data/localizations_serializer.rb
+- lib/product_taxonomy/models/serializers/attribute/dist/json_serializer.rb
+- lib/product_taxonomy/models/serializers/attribute/dist/txt_serializer.rb
+- lib/product_taxonomy/models/serializers/attribute/docs/base_and_extended_serializer.rb
+- lib/product_taxonomy/models/serializers/attribute/docs/reversed_serializer.rb
+- lib/product_taxonomy/models/serializers/attribute/docs/search_serializer.rb
+- lib/product_taxonomy/models/serializers/category/data/data_serializer.rb
+- lib/product_taxonomy/models/serializers/category/data/full_names_serializer.rb
+- lib/product_taxonomy/models/serializers/category/data/localizations_serializer.rb
+- lib/product_taxonomy/models/serializers/category/dist/json_serializer.rb
+- lib/product_taxonomy/models/serializers/category/dist/txt_serializer.rb
+- lib/product_taxonomy/models/serializers/category/docs/search_serializer.rb
+- lib/product_taxonomy/models/serializers/category/docs/siblings_serializer.rb
+- lib/product_taxonomy/models/serializers/value/data/data_serializer.rb
+- lib/product_taxonomy/models/serializers/value/data/localizations_serializer.rb
+- lib/product_taxonomy/models/serializers/value/dist/json_serializer.rb
+- lib/product_taxonomy/models/serializers/value/dist/txt_serializer.rb
+- lib/product_taxonomy/models/taxonomy.rb
+- lib/product_taxonomy/models/value.rb
+- lib/product_taxonomy/version.rb
+homepage: https://github.com/Shopify/product-taxonomy
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/Shopify/product-taxonomy/issues
+  source_code_uri: https://github.com/Shopify/product-taxonomy
+  allowed_push_host: https://rubygems.org
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Load the complete Shopify Standard Product Taxonomy into memory as a tree
+test_files: []