spree_api 6.0.0.rc1 → 6.0.0.rc3

data/app/controllers/concerns/spree/api/v3/store/search_provider_support.rb

@@ -18,12 +18,11 @@ module Spree
           private
 
           def search_query
-            params.dig(:q, :search)
+            search_params['search']
           end
 
           def search_filters
-            q = params[:q]&.to_unsafe_h || params[:q] || {}
-            q = q.to_h if q.respond_to?(:to_h) && !q.is_a?(Hash)
+            q = search_params
             # Decode Stripe-style prefixed IDs in `*_id_in`/`id_eq`/etc. so
             # SPA + storefront filters can pass `prod_…` keys; the search
             # provider hands the filter hash straight to Ransack on the
@@ -31,6 +30,12 @@ module Spree
             decode_prefixed_id_predicates(q.except('search')).presence
           end
 
+          # A `q` sent as anything but a hash (`q=foo`) filters nothing.
+          def search_params
+            q = params[:q]
+            q.respond_to?(:to_unsafe_h) ? q.to_unsafe_h : {}
+          end
+
           def search_provider
             @search_provider ||= Spree.search_provider.constantize.new(current_store)
           end

data/app/controllers/concerns/spree/api/v3/strict_money_params.rb

@@ -0,0 +1,94 @@
+module Spree
+  module Api
+    module V3
+      # Admin and Seller writes take money and rates as canonical decimal
+      # strings only ("19.99", "0.23"): a JSON number, localized text or more
+      # decimals than the field holds is answered with `invalid_money_format`
+      # before anything is written. A money field checks its currency's decimals
+      # when the payload names the currency beside it, and four otherwise; unit
+      # prices always allow four. Store API writes carry no amounts and are not
+      # checked here.
+      module StrictMoneyParams
+        extend ActiveSupport::Concern
+
+        MONEY_KEYS = %w[
+          amount compare_at_amount cost cost_price price unit_cost refund_amount settled_amount
+          minimum_payout_amount min_amount max_amount markup_flat
+          amount_min amount_max first_item additional_item minimal_amount normal_amount discount_amount
+          base_amount minimum_item_total maximum_item_total default_minimum_payout_amount
+          preferred_default_minimum_payout_amount
+        ].freeze
+
+        UNIT_PRICE_KEYS = %w[price compare_at_amount cost_price unit_cost].freeze
+
+        RATE_KEYS = %w[
+          rate rate_percent percent flat_percent base_percent markup_percent percentage
+          price_adjustment_percentage commission_tax_rate default_commission_tax_rate
+          preferred_default_commission_tax_rate
+        ].freeze
+
+        # Values the merchant or a provider owns, stored as sent.
+        OPAQUE_KEYS = %w[metadata custom_fields external_data].freeze
+
+        # Preferences are checked against their declared types when assigned
+        # (Spree::Preferences::Preferable#assign_preferences), so a money
+        # preference is recognized by its type rather than its name.
+        TYPED_KEYS = %w[preferences calculator_preferences].freeze
+
+        included do
+          before_action :refuse_noncanonical_decimals, if: -> { request.post? || request.patch? || request.put? }
+        end
+
+        private
+
+        def refuse_noncanonical_decimals
+          check_decimals(request.request_parameters, parent: nil, currency: nil)
+        end
+
+        def check_decimals(node, parent:, currency:)
+          case node
+          when Hash
+            currency = node['currency'].presence || currency
+            node.each do |key, value|
+              next if OPAQUE_KEYS.include?(key) || TYPED_KEYS.include?(key)
+
+              if scalar?(value) && MONEY_KEYS.include?(key)
+                check_money(key, value, currency, UNIT_PRICE_KEYS.include?(key) || (key == 'amount' && parent == 'prices'))
+              elsif scalar?(value) && RATE_KEYS.include?(key)
+                check_rate(key, value)
+              else
+                check_decimals(value, parent: key, currency: currency)
+              end
+            end
+          when Array
+            node.each { |item| check_decimals(item, parent: parent, currency: currency) }
+          end
+        end
+
+        def check_money(key, value, currency, unit_price)
+          return if blank_value?(value)
+
+          Spree::Money::Rounding.parse_canonical(value, currency.presence, unit_price: unit_price)
+        rescue Spree::Money::InvalidFormat => error
+          raise Spree::Money::InvalidFormat.new(error.message, field: key.to_sym)
+        end
+
+        def check_rate(key, value)
+          return if blank_value?(value)
+
+          Spree::Money::Rounding.parse_canonical_decimal(value)
+        rescue Spree::Money::InvalidFormat => error
+          raise Spree::Money::InvalidFormat.new(error.message, field: key.to_sym)
+        end
+
+        def scalar?(value)
+          !value.is_a?(Hash) && !value.is_a?(Array)
+        end
+
+        def blank_value?(value)
+          value.nil? || (value.is_a?(String) && value.strip.empty?)
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v3/admin/admin_users_controller.rb

@@ -14,6 +14,15 @@ module Spree
           # grantable separately from store configuration (6.0-admin-rbac.md).
           scoped_resource :staff
 
+          request_params :admin_user do |body|
+            body.attribute :first_name, :string
+            body.attribute :last_name, :string
+            # Applied through `apply_role_ids`, scoped to the current store.
+            body.attribute :role_ids, :array, of: :id,
+              permit: false,
+              description: "Role IDs of the current store the user should hold. Replaces the user's roles on this store; an empty list removes them all."
+          end
+
           # DELETE /api/v3/admin/admin_users/:id
           # Removes role assignments for the current store rather than deleting
           # the account globally. The user keeps access to any other stores.
@@ -79,7 +88,7 @@ module Spree
           private
 
           def identity_params
-            params.permit(:first_name, :last_name)
+            params.permit(*declared_permitted_attributes)
           end
 
           def role_ids_param

data/app/controllers/spree/api/v3/admin/allowed_origins_controller.rb

@@ -5,6 +5,13 @@ module Spree
         class AllowedOriginsController < ResourceController
           scoped_resource :settings
 
+          request_params :allowed_origin do |body|
+            body.attribute :origin, :string,
+              required: true, on: :create,
+              example: 'https://admin.example.com',
+              description: 'Origin to allow in admin CORS preflight checks: a bare `scheme://host[:port]` (no path, query or fragment) using `http` or `https`.'
+          end
+
           protected
 
           def model_class
@@ -16,7 +23,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :origin)
+            params.permit(*permitted_attributes)
           end
         end
       end

data/app/controllers/spree/api/v3/admin/api_keys_controller.rb

@@ -14,6 +14,20 @@ module Spree
           # `read_api_keys` — any key can describe itself.
           skip_scope_check! only: :current
 
+          # `key_type`, `scopes` and `channel_id` are create-only (immutability
+          # lives on Spree::ApiKey), so a rename returns 200 rather than 422.
+          request_params :api_key do |body|
+            body.attribute :name, :string, required: true
+            body.attribute :key_type, :string, required: true, only: :create, choices: Spree::ApiKey::KEY_TYPES
+            body.attribute :scopes, :array, of: :string,
+              only: :create,
+              example: %w[read_orders write_products],
+              description: 'Required for secret keys. You can only grant scopes you hold yourself. Fixed once created: to change them, create a new key and revoke the old one.'
+            body.attribute :channel_id, :id,
+              only: :create,
+              description: 'Binds a publishable key to one channel of the store (`ch_...`), so it rejects requests for other channels. Fixed once created; omit it for a store-wide key.'
+          end
+
           # POST /api/v3/admin/api_keys
           # Prevents scope amplification for BOTH principals: a key minted via a
           # secret API key can only carry scopes that key already holds, and a
@@ -94,16 +108,10 @@ module Spree
             end
           end
 
-          # `key_type`, `scopes`, and `channel_id` are create-only (immutability
-          # lives on Spree::ApiKey); update is limited to the human-facing `name`.
-          # Stripping them here keeps them out of mass assignment so a rename
-          # returns 200 rather than 422.
           # No extension union: an API key's scopes and type are the authorization
           # surface itself, not extensible resource data.
           def permitted_params
-            return params.permit(:name) if action_name == 'update'
-
-            params.permit(:name, :key_type, :channel_id, scopes: [])
+            params.permit(*declared_permitted_attributes)
           end
 
           private

data/app/controllers/spree/api/v3/admin/base_controller.rb

@@ -12,6 +12,7 @@ module Spree
           before_action :authenticate_admin!
 
           include Spree::Api::V3::ScopedAuthorization
+          include Spree::Api::V3::StrictMoneyParams
           include Spree::Api::V3::Admin::ValidationDetails
           include Spree::Api::V3::Admin::EmbedPermissions
         end

data/app/controllers/spree/api/v3/admin/catalogs/order_minimums_controller.rb

@@ -9,6 +9,8 @@ module Spree
           class OrderMinimumsController < BaseController
             before_action :authorize_parent_access!
 
+            request_params('CatalogOrderMinimumParams') { |body| body.include_attributes Spree::Api::V3::Admin::CatalogOrderMinimumRequestSchema }
+
             protected
 
             def model_class
@@ -24,7 +26,7 @@ module Spree
             end
 
             def permitted_params
-              params.permit(:currency, :amount)
+              params.permit(*declared_permitted_attributes)
             end
           end
         end

data/app/controllers/spree/api/v3/admin/catalogs/quantity_rules_controller.rb

@@ -20,12 +20,14 @@ module Spree
           class QuantityRulesController < BaseController
             before_action :authorize_parent_access!
 
+            request_params 'CatalogProductTermsParams', action: :upsert do |body|
+              body.attribute :terms, :hash,
+                required: true,
+                example: { 'prod_abc123' => { minimum_order_quantity: 48, order_multiple: 24 } },
+                description: 'Quantity terms keyed by product: `{ minimum_order_quantity, order_multiple }`, each a whole number or null. A product whose pair is both null has its terms cleared; a product not yet in the assortment is added.'
+            end
+
             # PUT /api/v3/admin/catalogs/:catalog_id/quantity_rules
-            #
-            # { terms: { "prod_abc": { minimum_order_quantity: 48,
-            #                          order_multiple: 24 } } }
-            #
-            # A product whose pair is both null has its terms cleared.
             def upsert
               authorize! :update, @catalog
 

data/app/controllers/spree/api/v3/admin/catalogs_controller.rb

@@ -6,12 +6,70 @@ module Spree
         # through assignments. Merchandising data, so it answers to the
         # products scopes.
         class CatalogsController < ResourceController
+          ASSIGNMENT = Spree::Api::V3::RequestSchema.shape('CatalogAssignmentParams') do |schema|
+            schema.attribute :assignable_type, :string,
+              required: true,
+              choices: %w[customer_group company],
+              example: 'company',
+              description: 'Buyer audiences only. A company assignment covers its subtree.'
+            schema.attribute :assignable_id, :id, required: true, example: 'comp_86Rf07xd4z'
+          end
+
           scoped_resource :products
 
           before_action :set_resource,
                         only: [:show, :update, :destroy, :assign, :import_products,
                                :activate, :deactivate]
 
+          request_params :catalog do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'VIP Assortment'
+            body.attribute :description, :string,
+              nullable: true,
+              description: 'Internal note on what the agreement is, never shown to shoppers.'
+            body.attribute :active, :boolean, example: true
+            body.attribute :position, :integer
+            body.attribute :minimum_order_quantity, :integer,
+              nullable: true,
+              description: "The catalog-wide quantity terms, between a variant's own rule and a per-variant override. Null leaves the field to the variant's own rule."
+            body.attribute :order_multiple, :integer,
+              nullable: true,
+              description: "The catalog-wide quantity terms, between a variant's own rule and a per-variant override. Null leaves the field to the variant's own rule."
+            body.attribute :metadata, :hash
+            # Small bounded sets, saved with the catalog so the whole
+            # agreement lands in one transaction. Per-product terms stay their
+            # own endpoint: an agreement may name thousands of them.
+            body.attribute :assignments, :array, of: ASSIGNMENT,
+              description: 'The whole audience. An entry left out is withdrawn; omitting the key leaves the audience alone.'
+            body.attribute :order_minimums, :array, of: Spree::Api::V3::Admin::CatalogOrderMinimumRequestSchema,
+              description: 'The whole order-minimum set. A currency left out has its minimum lifted; omitting the key leaves them alone.'
+            body.attribute :price_list, :object,
+              nullable: true,
+              as: 'CatalogPriceListParams',
+              description: 'The price list this catalog prices through, written inline: an object creates the owned list or updates it. Null deletes the list (a soft delete). Omit the key, or send `{}`, to leave the pricing alone. A catalog with an empty assortment prices without hiding anything; curate or import products to make it restrictive.' do |price_list|
+              price_list.attribute :name, :string
+              price_list.attribute :description, :string, nullable: true
+              price_list.attribute :status, :string
+              price_list.attribute :match_policy, :string
+              price_list.attribute :starts_at, :datetime, nullable: true
+              price_list.attribute :ends_at, :datetime, nullable: true
+              price_list.attribute :price_adjustment_percentage, :decimal,
+                nullable: true,
+                example: '-15.0',
+                description: 'Signed: negative discounts off base prices, positive marks up.'
+              price_list.attribute :adjust_compare_at, :boolean
+              # Audience rules on an owned list are inert, since the catalog
+              # assignment already decided the audience.
+              price_list.attribute :rules, :array, of: Spree::Api::V3::Admin::PriceListRuleRequestSchema,
+                description: "Contextual rules, in practice a `volume_rule`. Audience rules are left as they are, and an empty list clears the contextual rules."
+              price_list.attribute :prices, :array, of: Spree::Api::V3::Admin::PriceListPriceRequestSchema,
+                description: 'Explicit per-variant amounts. An empty list clears them, which is what switching to a percentage sends.'
+              price_list.attribute :price_adjustment_tiers, :array, of: Spree::Api::V3::Admin::PriceAdjustmentTierRequestSchema,
+                description: 'Quantity bands on the percentage. The payload is the whole ladder, so an empty list clears it.'
+            end
+          end
+
+          request_params('CatalogAssignParams', action: :assign) { |body| body.include_attributes ASSIGNMENT }
+
           # POST /api/v3/admin/catalogs/:id/import_products — copies the
           # attached price list's products into the assortment. Explicit by
           # design: an empty assortment is a pricing-only overlay, so making
@@ -30,7 +88,7 @@ module Spree
             render json: { added_count: @resource.import_products_from_price_list }
           end
 
-          # POST /api/v3/admin/catalogs/:id/assign — { assignable_type, assignable_id }
+          # POST /api/v3/admin/catalogs/:id/assign
           def assign
             authorize! :update, @resource
 
@@ -102,38 +160,7 @@ module Spree
           # as `null` detaches the list the catalog owns; omitting the key
           # leaves it alone.
           def permitted_params
-            permitted = params.permit(*model_additional_permitted_attributes,
-                                      :name, :description, :active, :position,
-                                      :minimum_order_quantity, :order_multiple,
-                                      metadata: {},
-                                      # Small bounded sets, saved with the
-                                      # catalog so the whole agreement lands
-                                      # in one transaction. Per-product terms
-                                      # stay their own endpoint — an
-                                      # agreement may name thousands of them.
-                                      assignments: [:assignable_type, :assignable_id],
-                                      order_minimums: [:currency, :amount],
-                                      price_list: [
-                                        :name, :description, :status, :match_policy,
-                                        :starts_at, :ends_at,
-                                        :price_adjustment_percentage, :adjust_compare_at,
-                                        # Contextual rules only in practice — a
-                                        # VolumeRule is what turns a percentage
-                                        # into automatic volume pricing. Audience
-                                        # rules on an owned list are inert, since
-                                        # the catalog assignment already decided
-                                        # the audience.
-                                        { rules: [:id, :type, { preferences: {} }] },
-                                        # An empty array clears the hand-entered
-                                        # amounts — what switching to a
-                                        # percentage sends.
-                                        { prices: [:id, :variant_id, :currency, :min_quantity,
-                                                   :amount, :compare_at_amount] },
-                                        # Quantity bands on the percentage. The
-                                        # payload is the whole ladder, so an
-                                        # empty array clears it.
-                                        { price_adjustment_tiers: [:min_quantity, :percentage] }
-                                      ])
+            permitted = params.permit(*permitted_attributes)
             # `permit` drops an explicit null, but detaching has to be
             # distinguishable from saying nothing.
             permitted[:price_list] = nil if params.key?(:price_list) && params[:price_list].nil?

data/app/controllers/spree/api/v3/admin/categories/products_controller.rb

@@ -15,8 +15,11 @@ module Spree
 
             before_action :set_product, only: [:reposition]
 
+            request_params 'ProductMembershipRepositionParams', action: :reposition do |body|
+              body.include_attributes Spree::Api::V3::Admin::ProductMembershipRepositionRequestSchema
+            end
+
             # PATCH /api/v3/admin/categories/:category_id/products/:id/reposition
-            # Body: { new_position: 0 } — 0-based index among the category's products.
             # @product is already constrained to the category's scope, so a
             # classification always exists.
             def reposition

data/app/controllers/spree/api/v3/admin/categories_controller.rb

@@ -11,8 +11,46 @@ module Spree
         class CategoriesController < ResourceController
           scoped_resource :categories
 
+          # Category-half attributes only. The collection-bound fields
+          # (automatic, sort_order, rules) belong to Spree::Collection, and
+          # taxonomy_id is gone with Taxonomy.
+          request_params :category do |body|
+            body.external_references
+            body.attribute :name, :string, required: true, on: :create, example: 'Shirts'
+            # Resolved within scope by +permitted_params+, so a parent from
+            # another store or an automatic taxon can't be targeted.
+            body.attribute :parent_id, :id,
+              nullable: true,
+              permit: false,
+              example: 'ctg_abc123',
+              description: 'The parent category. Omitted or null, a new category goes to the top level and an existing one keeps its parent: moving one to the top level is the reposition endpoint.'
+            body.attribute :description, :string,
+              description: 'Rich text HTML. Reads come back as this (plain text) plus `description_html`.'
+            body.attribute :permalink, :string
+            body.attribute :meta_title, :string
+            body.attribute :meta_description, :string
+            body.attribute :meta_keywords, :string
+            body.attribute :image_signed_id, :string,
+              nullable: true,
+              description: 'A `signed_id` from `files.upload()` for the landscape image, or null to remove it.'
+            body.attribute :square_image_signed_id, :string,
+              nullable: true,
+              description: 'A `signed_id` from `files.upload()` for the square image, or null to remove it.'
+            body.attribute :custom_fields, :array, of: Spree::Api::V3::CustomFieldValueRequestSchema,
+              description: 'Custom field values, each validated against its definition.'
+          end
+
+          request_params 'CategoryRepositionParams', action: :reposition do |body|
+            body.attribute :new_parent_id, :id,
+              nullable: true,
+              description: 'The new parent. Omit or null to move the category to the top level.'
+            body.attribute :new_position, :integer,
+              required: true,
+              example: 0,
+              description: "0-based index among the new parent's children."
+          end
+
           # PATCH /api/v3/admin/categories/:id/reposition
-          # Body: { new_parent_id: 'ctg_…' (omit for top level), new_position: 0 }
           # Moves the category to a new parent (or the top level) and/or index.
           def reposition
             category = find_resource
@@ -59,26 +97,8 @@ module Spree
             super.manual
           end
 
-          # Category-half attributes only. Deliberately excludes the
-          # collection-bound fields (automatic, sort_order, rules_match_policy,
-          # taxon_rules) and taxonomy_id — those belong to Spree::Collection
-          # (6.0) and Taxonomy is being dropped. A prefixed parent_id resolves
-          # within scope (so a parent from another store or an automatic taxon
-          # can't be targeted).
           def permitted_params
-            permitted = params.permit(
-              *model_additional_permitted_attributes,
-              :name, :description, :permalink,
-              :meta_title, :meta_description, :meta_keywords,
-              :image, :square_image,
-              # Inline custom field values keyed by definition id. The model
-              # setter (Spree::HasCustomFields#custom_fields=) validates each entry
-              # against its definition. `value` is permitted as a scalar AND as
-              # `value: []` / `value: {}` so JSON custom_fields round-trip whether
-              # the parsed payload is an array or an object, while
-              # text/number/boolean ship scalars.
-              custom_fields: [:id, :custom_field_definition_id, :value, { value: [] }, { value: {} }]
-            )
+            permitted = params.permit(*permitted_attributes)
             permitted[:parent] = scope.find_by_prefix_id!(params[:parent_id]) if params[:parent_id].present?
             permitted
           end

data/app/controllers/spree/api/v3/admin/channels_controller.rb

@@ -5,8 +5,45 @@ module Spree
         class ChannelsController < ResourceController
           scoped_resource :settings
 
+          request_params :channel do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'Point of Sale'
+            body.attribute :code, :string,
+              example: 'pos',
+              description: 'URL-safe slug, derived from `name` when blank (`Point of Sale` becomes `point-of-sale`).'
+            body.attribute :active, :boolean
+            body.attribute :default, :boolean
+            body.attribute :order_routing_strategy, :string,
+              nullable: true,
+              description: 'Order routing strategy shorthand (built-in: `rules`). Null inherits the store setting.'
+            body.attribute :storefront_access, :string,
+              nullable: true,
+              choices: Spree::Channel::Gating::STOREFRONT_ACCESS,
+              description: 'What anonymous visitors can see. Null inherits the store setting.'
+            body.attribute :guest_checkout, :boolean,
+              nullable: true,
+              description: 'Whether guests can check out without an account. Null inherits the store setting.'
+            body.attribute :default_catalog_id, :id,
+              nullable: true,
+              description: 'Catalog (`cat_...`) shown to shoppers no company or customer group catalog covers. Null means every product published on the channel.'
+            body.attribute :stock_location_ids, :array, of: :id,
+              description: 'Stock locations (`sloc_...`) that fulfill this channel. Replaces the whole set; an empty list means every location of the store.'
+          end
+
+          request_params 'ChannelAddProductsParams', action: :add_products do |body|
+            body.attribute :product_ids, :array, of: :id, required: true
+            body.attribute :published_at, :datetime,
+              nullable: true,
+              description: 'When the publications go live. Null means immediately.'
+            body.attribute :unpublished_at, :datetime,
+              nullable: true,
+              description: 'When the publications come down. Null means never.'
+          end
+
+          request_params 'ChannelRemoveProductsParams', action: :remove_products do |body|
+            body.attribute :product_ids, :array, of: :id, required: true
+          end
+
           # POST /api/v3/admin/channels/:id/add_products
-          # Body: { product_ids: [...], published_at: nil, unpublished_at: nil }
           def add_products
             channel = find_resource
             authorize! :update, channel
@@ -20,7 +57,6 @@ module Spree
           end
 
           # POST /api/v3/admin/channels/:id/remove_products
-          # Body: { product_ids: [...] }
           def remove_products
             channel = find_resource
             authorize! :update, channel
@@ -61,10 +97,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :name, :code, :active, :default, :preferred_order_routing_strategy,
-                          :preferred_storefront_access, :preferred_guest_checkout,
-                          :default_catalog_id,
-                          stock_location_ids: [])
+            params.permit(*permitted_attributes)
           end
 
           # `stock_location_ids` replaces the channel's fulfillment-origin

data/app/controllers/spree/api/v3/admin/claim_reasons_controller.rb

@@ -5,6 +5,10 @@ module Spree
         class ClaimReasonsController < ResourceController
           scoped_resource :settings
 
+          request_params :reason do |body|
+            body.include_attributes Spree::Api::V3::Admin::ReasonRequestSchema
+          end
+
           protected
 
           def model_class
@@ -16,7 +20,7 @@ module Spree
           end
 
           def permitted_params
-            params.permit(*model_additional_permitted_attributes, :name, :active)
+            params.permit(*permitted_attributes)
           end
         end
       end

data/app/controllers/spree/api/v3/admin/collections/products_controller.rb

@@ -17,8 +17,11 @@ module Spree
             before_action :ensure_manual_collection, only: [:create, :destroy, :reposition]
             before_action :set_product, only: [:reposition]
 
+            request_params 'ProductMembershipRepositionParams', action: :reposition do |body|
+              body.include_attributes Spree::Api::V3::Admin::ProductMembershipRepositionRequestSchema
+            end
+
             # PATCH /api/v3/admin/collections/:collection_id/products/:id/reposition
-            # Body: { new_position: 0 } — 0-based index among the collection's products.
             # @product is already constrained to the collection's scope, so a
             # ProductCollection always exists.
             def reposition

data/app/controllers/spree/api/v3/admin/collections_controller.rb

@@ -10,6 +10,47 @@ module Spree
         class CollectionsController < ResourceController
           scoped_resource :collections
 
+          request_params :collection do |body|
+            body.attribute :name, :string, required: true, on: :create, example: 'On Sale'
+            body.attribute :description, :string,
+              description: 'Rich text HTML. Reads come back as this (plain text) plus `description_html`.'
+            body.attribute :permalink, :string
+            body.attribute :position, :integer,
+              description: "1-based position among the store's collections; the server shifts its siblings. The nested products reposition endpoints, unlike this, take 0-based indexes."
+            body.attribute :meta_title, :string
+            body.attribute :meta_description, :string
+            body.attribute :meta_keywords, :string
+            body.attribute :image_signed_id, :string,
+              nullable: true,
+              description: 'A `signed_id` from `files.upload()` for the landscape image, or null to remove it.'
+            body.attribute :square_image_signed_id, :string,
+              nullable: true,
+              description: 'A `signed_id` from `files.upload()` for the square image, or null to remove it.'
+            body.attribute :automatic, :boolean,
+              description: 'When true, membership is materialized from `rules` instead of curated by hand.'
+            body.attribute :rules_match_policy, :string,
+              choices: Spree::Collection::RULES_MATCH_POLICIES,
+              description: 'Whether a product must match all rules or any of them. Defaults to `all`.'
+            body.attribute :sort_order, :string,
+              choices: Spree::Collection::SORT_ORDERS,
+              description: "Default product sort for the storefront listing; a shopper's own sort wins. Defaults to `manual`."
+            # Applied by the model's sync setter (Spree::Collection#rules=).
+            body.attribute :rules, :array,
+              as: 'CollectionRuleParams',
+              description: 'The complete desired rule set. Entries with an `id` update, entries without one are created, and existing rules left out are removed.' do |rule|
+              rule.attribute :id, :id, example: 'crule_abc123', description: 'Omit to create a new rule.'
+              rule.attribute :type, :string,
+                example: 'tag',
+                description: 'Wire shorthand for the rule kind, from the collection rule types endpoint.'
+              rule.attribute :value, :string, example: 'summer'
+              rule.attribute :match_policy, :string,
+                choices: Spree::CollectionRule::MATCH_POLICIES,
+                example: 'contains'
+            end
+            body.attribute :custom_fields, :array, of: Spree::Api::V3::CustomFieldValueRequestSchema,
+              description: 'Custom field values, each validated against its definition.'
+          end
+
           protected
 
           def model_class
@@ -32,22 +73,10 @@ module Spree
             super.ordered
           end
 
-          # Flat params. +rules+ is applied by the model's sync setter
-          # (Spree::Collection#rules=): the full desired rule set, prefixed
-          # +crule_+ ids update, missing ids build, omitted rules are removed —
-          # so normalize_params is deliberately NOT called (that would rewrite
-          # +rules+ to +rules_attributes+ and route past the setter).
+          # normalize_params is deliberately NOT called: it would rewrite
+          # +rules+ to +rules_attributes+ and route past the sync setter.
           def permitted_params
-            params.permit(
-              :name, :description, :permalink, :position,
-              :meta_title, :meta_description, :meta_keywords,
-              :image, :square_image,
-              :automatic, :rules_match_policy, :sort_order,
-              rules: [:id, :type, :value, :match_policy],
-              # Inline custom field values keyed by definition id (see
-              # CategoriesController#permitted_params for the value shapes).
-              custom_fields: [:id, :custom_field_definition_id, :value, { value: [] }, { value: {} }]
-            )
+            params.permit(*permitted_attributes)
           end
         end
       end