id: https://nde.nl/ontology/hc/class/CommissionRate
name: commission_rate_class
title: Commission Rate Class

prefixes:
  linkml: https://w3id.org/linkml/
  hc: https://nde.nl/ontology/hc/
  schema: http://schema.org/

imports:
  - linkml:types
  - ../metadata
  - ../slots/has_or_had_percentage
  - ./Percentage

default_prefix: hc

classes:
  CommissionRate:
    class_uri: hc:CommissionRate
    description: |
      Structured representation of a commission rate.
      
      **PURPOSE**:
      
      Models commission percentages with context (market type,
      rate type) replacing simple string representation.
      
      **DESIGN RATIONALE**:
      
      Created per slot_fixes.yaml migration from `commission_rate` string
      to structured representation with Percentage class.
      
      **ART MARKET STANDARDS**:
      
      - **Primary market**: 40-50% standard (gallery takes half)
      - **Secondary market**: 10-20% (resale commission)
      - **Auction**: 10-25% buyer's premium + seller's commission
      
      **EXAMPLE**:
      
      ```yaml
      takes_or_took_comission:
        rate_type: "primary_market"
        has_or_had_percentage:
          percentage_value: 50
          percentage_display: "50%"
      ```
    
    close_mappings:
      - schema:PriceSpecification
    
    slots:
      - has_or_had_percentage
    
    attributes:
      rate_type:
        description: |
          Type of commission rate.
        range: string
        required: false
        examples:
          - value: "primary_market"
            description: Commission on first sale
          - value: "secondary_market"
            description: Commission on resale
          - value: "auction_buyers_premium"
            description: Auction house buyer's premium
          - value: "auction_sellers_commission"
            description: Auction house seller's commission
      
      rate_description:
        description: |
          Human-readable description of the commission structure.
        range: string
        required: false
        examples:
          - value: "Standard 50/50 split between gallery and artist"
            description: Primary market explanation
          - value: "Sliding scale based on sale price"
            description: Variable commission description
      
      effective_date:
        description: |
          When this commission rate became effective.
        range: date
        required: false
      
      applies_to:
        description: |
          What this commission rate applies to.
        range: string
        required: false
        examples:
          - value: "All represented artists"
            description: Gallery-wide rate
          - value: "Works over €10,000"
            description: Price-based rate
    
    slot_usage:
      has_or_had_percentage:
        description: |
          The percentage value of this commission rate.
        range: Percentage
        inlined: true
        required: true
        examples:
          - value:
              percentage_value: 50
              percentage_display: "50%"
            description: 50% commission
    
    examples:
      - value:
          rate_type: "primary_market"
          rate_description: "Standard 50/50 split between gallery and artist"
          has_or_had_percentage:
            percentage_value: 50
            percentage_display: "50%"
        description: Standard primary market commission
      
      - value:
          rate_type: "secondary_market"
          rate_description: "Consignment fee for resale works"
          has_or_had_percentage:
            percentage_value: 15
            percentage_min: 10
            percentage_max: 20
            percentage_display: "10-20%"
        description: Variable secondary market commission
      
      - value:
          rate_type: "auction_buyers_premium"
          rate_description: "Buyer's premium at auction"
          has_or_had_percentage:
            percentage_value: 25
            percentage_display: "25%"
        description: Auction house buyer's premium
    
    comments:
      - Created 2026-01-22 from commission_rate migration (Rule 53)
      - Provides structured commission representation
      - Supports art market commission conventions
    
    see_also:
      - https://schema.org/PriceSpecification
    
    annotations:
      custodian_types: '["G", "C"]'
      custodian_types_rationale: >-
        Primarily for galleries (G) and commercial organizations (C).
      specificity_score: "0.80"
      specificity_rationale: >-
        Specific to commercial sales commission context.