backbone-catalog 0.7.0

openapi: '3.0.3'
info:
  title: Backbone API
  version: '1.0.0'
  description: |
    Auto-generated by backbone-cli.
    This API provides 11 standard CRUD endpoints for each model.

servers:
  - url: /
    description: Development server

tags:
  - name: Attributes
    description: Attribute management endpoints
  - name: AttributeValues
    description: AttributeValue management endpoints
  - name: Brands
    description: Brand management endpoints
  - name: Items
    description: Item management endpoints
  - name: ItemGroups
    description: ItemGroup management endpoints
  - name: ItemVariants
    description: ItemVariant management endpoints
  - name: Uoms
    description: Uom management endpoints
  - name: UomConversions
    description: UomConversion management endpoints

paths:
  /api/v1/catalog/attributes:
    get:
      tags:
        - Attributes
      summary: List Attributes
      description: Get a paginated list of Attributes with optional filtering and sorting
      operationId: listAttributes
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - Attributes
      summary: Create Attribute
      description: Create a new Attribute
      operationId: createAttribute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAttributeRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attribute'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/catalog/attributes/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - Attributes
      summary: Get Attribute by ID
      operationId: getAttribute
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attribute'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - Attributes
      summary: Update Attribute (full)
      operationId: updateAttribute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAttributeRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attribute'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - Attributes
      summary: Update Attribute (partial)
      operationId: patchAttribute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchAttributeRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attribute'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - Attributes
      summary: Delete Attribute (soft)
      operationId: deleteAttribute
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/catalog/attributes/bulk:
    post:
      tags:
        - Attributes
      summary: Bulk create Attributes
      operationId: bulkCreateAttributes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateAttributeRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Attribute'
    put:
      tags:
        - Attributes
      summary: Bulk update Attributes (full, atomic)
      operationId: bulkUpdateAttributes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateAttributeRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - Attributes
      summary: Bulk partial-update Attributes (atomic)
      operationId: bulkPatchAttributes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/attributes/upsert:
    post:
      tags:
        - Attributes
      summary: Upsert Attribute
      operationId: upsertAttribute
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAttributeRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attribute'

  /api/v1/catalog/attributes/trash:
    get:
      tags:
        - Attributes
      summary: List deleted Attributes
      operationId: listDeletedAttributes
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeList'

  /api/v1/catalog/attributes/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - Attributes
      summary: Restore deleted Attribute
      operationId: restoreAttribute
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attribute'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/catalog/attributes/empty:
    delete:
      tags:
        - Attributes
      summary: Empty trash for Attributes
      operationId: emptyTrashAttributes
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/catalog/attributes/delete/bulk:
    post:
      tags:
        - Attributes
      summary: Bulk soft-delete Attributes by ids (atomic)
      operationId: bulkDeleteAttributes
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/attributes/restore/bulk:
    post:
      tags:
        - Attributes
      summary: Bulk restore Attributes by ids (atomic)
      operationId: bulkRestoreAttributes
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/attributes/restore/all:
    post:
      tags:
        - Attributes
      summary: Restore all soft-deleted Attributes
      operationId: restoreAllAttributes
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/catalog/attributes/trash/bulk:
    delete:
      tags:
        - Attributes
      summary: Bulk permanently-delete Attributes from trash by ids (atomic)
      operationId: bulkPermanentDeleteAttributes
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/attribute_values:
    get:
      tags:
        - AttributeValues
      summary: List AttributeValues
      description: Get a paginated list of AttributeValues with optional filtering and sorting
      operationId: listAttributeValues
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeValueList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - AttributeValues
      summary: Create AttributeValue
      description: Create a new AttributeValue
      operationId: createAttributeValue
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAttributeValueRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeValue'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/catalog/attribute_values/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - AttributeValues
      summary: Get AttributeValue by ID
      operationId: getAttributeValue
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeValue'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - AttributeValues
      summary: Update AttributeValue (full)
      operationId: updateAttributeValue
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAttributeValueRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeValue'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - AttributeValues
      summary: Update AttributeValue (partial)
      operationId: patchAttributeValue
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchAttributeValueRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeValue'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - AttributeValues
      summary: Delete AttributeValue (soft)
      operationId: deleteAttributeValue
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/catalog/attribute_values/bulk:
    post:
      tags:
        - AttributeValues
      summary: Bulk create AttributeValues
      operationId: bulkCreateAttributeValues
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateAttributeValueRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AttributeValue'
    put:
      tags:
        - AttributeValues
      summary: Bulk update AttributeValues (full, atomic)
      operationId: bulkUpdateAttributeValues
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateAttributeValueRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeValueBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - AttributeValues
      summary: Bulk partial-update AttributeValues (atomic)
      operationId: bulkPatchAttributeValues
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeValueBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/attribute_values/upsert:
    post:
      tags:
        - AttributeValues
      summary: Upsert AttributeValue
      operationId: upsertAttributeValue
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAttributeValueRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeValue'

  /api/v1/catalog/attribute_values/trash:
    get:
      tags:
        - AttributeValues
      summary: List deleted AttributeValues
      operationId: listDeletedAttributeValues
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeValueList'

  /api/v1/catalog/attribute_values/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - AttributeValues
      summary: Restore deleted AttributeValue
      operationId: restoreAttributeValue
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeValue'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/catalog/attribute_values/empty:
    delete:
      tags:
        - AttributeValues
      summary: Empty trash for AttributeValues
      operationId: emptyTrashAttributeValues
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/catalog/attribute_values/delete/bulk:
    post:
      tags:
        - AttributeValues
      summary: Bulk soft-delete AttributeValues by ids (atomic)
      operationId: bulkDeleteAttributeValues
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/attribute_values/restore/bulk:
    post:
      tags:
        - AttributeValues
      summary: Bulk restore AttributeValues by ids (atomic)
      operationId: bulkRestoreAttributeValues
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeValueBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/attribute_values/restore/all:
    post:
      tags:
        - AttributeValues
      summary: Restore all soft-deleted AttributeValues
      operationId: restoreAllAttributeValues
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/catalog/attribute_values/trash/bulk:
    delete:
      tags:
        - AttributeValues
      summary: Bulk permanently-delete AttributeValues from trash by ids (atomic)
      operationId: bulkPermanentDeleteAttributeValues
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/brands:
    get:
      tags:
        - Brands
      summary: List Brands
      description: Get a paginated list of Brands with optional filtering and sorting
      operationId: listBrands
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - Brands
      summary: Create Brand
      description: Create a new Brand
      operationId: createBrand
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBrandRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/catalog/brands/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - Brands
      summary: Get Brand by ID
      operationId: getBrand
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - Brands
      summary: Update Brand (full)
      operationId: updateBrand
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBrandRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - Brands
      summary: Update Brand (partial)
      operationId: patchBrand
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchBrandRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - Brands
      summary: Delete Brand (soft)
      operationId: deleteBrand
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/catalog/brands/bulk:
    post:
      tags:
        - Brands
      summary: Bulk create Brands
      operationId: bulkCreateBrands
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateBrandRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Brand'
    put:
      tags:
        - Brands
      summary: Bulk update Brands (full, atomic)
      operationId: bulkUpdateBrands
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateBrandRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - Brands
      summary: Bulk partial-update Brands (atomic)
      operationId: bulkPatchBrands
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/brands/upsert:
    post:
      tags:
        - Brands
      summary: Upsert Brand
      operationId: upsertBrand
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBrandRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'

  /api/v1/catalog/brands/trash:
    get:
      tags:
        - Brands
      summary: List deleted Brands
      operationId: listDeletedBrands
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandList'

  /api/v1/catalog/brands/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - Brands
      summary: Restore deleted Brand
      operationId: restoreBrand
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brand'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/catalog/brands/empty:
    delete:
      tags:
        - Brands
      summary: Empty trash for Brands
      operationId: emptyTrashBrands
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/catalog/brands/delete/bulk:
    post:
      tags:
        - Brands
      summary: Bulk soft-delete Brands by ids (atomic)
      operationId: bulkDeleteBrands
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/brands/restore/bulk:
    post:
      tags:
        - Brands
      summary: Bulk restore Brands by ids (atomic)
      operationId: bulkRestoreBrands
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/brands/restore/all:
    post:
      tags:
        - Brands
      summary: Restore all soft-deleted Brands
      operationId: restoreAllBrands
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/catalog/brands/trash/bulk:
    delete:
      tags:
        - Brands
      summary: Bulk permanently-delete Brands from trash by ids (atomic)
      operationId: bulkPermanentDeleteBrands
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/items:
    get:
      tags:
        - Items
      summary: List Items
      description: Get a paginated list of Items with optional filtering and sorting
      operationId: listItems
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - Items
      summary: Create Item
      description: Create a new Item
      operationId: createItem
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateItemRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/catalog/items/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - Items
      summary: Get Item by ID
      operationId: getItem
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - Items
      summary: Update Item (full)
      operationId: updateItem
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateItemRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - Items
      summary: Update Item (partial)
      operationId: patchItem
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchItemRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - Items
      summary: Delete Item (soft)
      operationId: deleteItem
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/catalog/items/bulk:
    post:
      tags:
        - Items
      summary: Bulk create Items
      operationId: bulkCreateItems
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateItemRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Item'
    put:
      tags:
        - Items
      summary: Bulk update Items (full, atomic)
      operationId: bulkUpdateItems
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateItemRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - Items
      summary: Bulk partial-update Items (atomic)
      operationId: bulkPatchItems
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/items/upsert:
    post:
      tags:
        - Items
      summary: Upsert Item
      operationId: upsertItem
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateItemRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'

  /api/v1/catalog/items/trash:
    get:
      tags:
        - Items
      summary: List deleted Items
      operationId: listDeletedItems
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemList'

  /api/v1/catalog/items/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - Items
      summary: Restore deleted Item
      operationId: restoreItem
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/catalog/items/empty:
    delete:
      tags:
        - Items
      summary: Empty trash for Items
      operationId: emptyTrashItems
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/catalog/items/delete/bulk:
    post:
      tags:
        - Items
      summary: Bulk soft-delete Items by ids (atomic)
      operationId: bulkDeleteItems
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/items/restore/bulk:
    post:
      tags:
        - Items
      summary: Bulk restore Items by ids (atomic)
      operationId: bulkRestoreItems
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/items/restore/all:
    post:
      tags:
        - Items
      summary: Restore all soft-deleted Items
      operationId: restoreAllItems
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/catalog/items/trash/bulk:
    delete:
      tags:
        - Items
      summary: Bulk permanently-delete Items from trash by ids (atomic)
      operationId: bulkPermanentDeleteItems
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/item_groups:
    get:
      tags:
        - ItemGroups
      summary: List ItemGroups
      description: Get a paginated list of ItemGroups with optional filtering and sorting
      operationId: listItemGroups
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemGroupList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - ItemGroups
      summary: Create ItemGroup
      description: Create a new ItemGroup
      operationId: createItemGroup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateItemGroupRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemGroup'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/catalog/item_groups/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - ItemGroups
      summary: Get ItemGroup by ID
      operationId: getItemGroup
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemGroup'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - ItemGroups
      summary: Update ItemGroup (full)
      operationId: updateItemGroup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateItemGroupRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemGroup'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - ItemGroups
      summary: Update ItemGroup (partial)
      operationId: patchItemGroup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchItemGroupRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemGroup'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - ItemGroups
      summary: Delete ItemGroup (soft)
      operationId: deleteItemGroup
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/catalog/item_groups/bulk:
    post:
      tags:
        - ItemGroups
      summary: Bulk create ItemGroups
      operationId: bulkCreateItemGroups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateItemGroupRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ItemGroup'
    put:
      tags:
        - ItemGroups
      summary: Bulk update ItemGroups (full, atomic)
      operationId: bulkUpdateItemGroups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateItemGroupRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemGroupBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - ItemGroups
      summary: Bulk partial-update ItemGroups (atomic)
      operationId: bulkPatchItemGroups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemGroupBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/item_groups/upsert:
    post:
      tags:
        - ItemGroups
      summary: Upsert ItemGroup
      operationId: upsertItemGroup
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateItemGroupRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemGroup'

  /api/v1/catalog/item_groups/trash:
    get:
      tags:
        - ItemGroups
      summary: List deleted ItemGroups
      operationId: listDeletedItemGroups
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemGroupList'

  /api/v1/catalog/item_groups/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - ItemGroups
      summary: Restore deleted ItemGroup
      operationId: restoreItemGroup
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemGroup'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/catalog/item_groups/empty:
    delete:
      tags:
        - ItemGroups
      summary: Empty trash for ItemGroups
      operationId: emptyTrashItemGroups
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/catalog/item_groups/delete/bulk:
    post:
      tags:
        - ItemGroups
      summary: Bulk soft-delete ItemGroups by ids (atomic)
      operationId: bulkDeleteItemGroups
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/item_groups/restore/bulk:
    post:
      tags:
        - ItemGroups
      summary: Bulk restore ItemGroups by ids (atomic)
      operationId: bulkRestoreItemGroups
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemGroupBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/item_groups/restore/all:
    post:
      tags:
        - ItemGroups
      summary: Restore all soft-deleted ItemGroups
      operationId: restoreAllItemGroups
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/catalog/item_groups/trash/bulk:
    delete:
      tags:
        - ItemGroups
      summary: Bulk permanently-delete ItemGroups from trash by ids (atomic)
      operationId: bulkPermanentDeleteItemGroups
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/item_variants:
    get:
      tags:
        - ItemVariants
      summary: List ItemVariants
      description: Get a paginated list of ItemVariants with optional filtering and sorting
      operationId: listItemVariants
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemVariantList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - ItemVariants
      summary: Create ItemVariant
      description: Create a new ItemVariant
      operationId: createItemVariant
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateItemVariantRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemVariant'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/catalog/item_variants/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - ItemVariants
      summary: Get ItemVariant by ID
      operationId: getItemVariant
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemVariant'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - ItemVariants
      summary: Update ItemVariant (full)
      operationId: updateItemVariant
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateItemVariantRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemVariant'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - ItemVariants
      summary: Update ItemVariant (partial)
      operationId: patchItemVariant
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchItemVariantRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemVariant'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - ItemVariants
      summary: Delete ItemVariant (soft)
      operationId: deleteItemVariant
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/catalog/item_variants/bulk:
    post:
      tags:
        - ItemVariants
      summary: Bulk create ItemVariants
      operationId: bulkCreateItemVariants
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateItemVariantRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ItemVariant'
    put:
      tags:
        - ItemVariants
      summary: Bulk update ItemVariants (full, atomic)
      operationId: bulkUpdateItemVariants
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateItemVariantRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemVariantBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - ItemVariants
      summary: Bulk partial-update ItemVariants (atomic)
      operationId: bulkPatchItemVariants
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemVariantBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/item_variants/upsert:
    post:
      tags:
        - ItemVariants
      summary: Upsert ItemVariant
      operationId: upsertItemVariant
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateItemVariantRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemVariant'

  /api/v1/catalog/item_variants/trash:
    get:
      tags:
        - ItemVariants
      summary: List deleted ItemVariants
      operationId: listDeletedItemVariants
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemVariantList'

  /api/v1/catalog/item_variants/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - ItemVariants
      summary: Restore deleted ItemVariant
      operationId: restoreItemVariant
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemVariant'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/catalog/item_variants/empty:
    delete:
      tags:
        - ItemVariants
      summary: Empty trash for ItemVariants
      operationId: emptyTrashItemVariants
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/catalog/item_variants/delete/bulk:
    post:
      tags:
        - ItemVariants
      summary: Bulk soft-delete ItemVariants by ids (atomic)
      operationId: bulkDeleteItemVariants
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/item_variants/restore/bulk:
    post:
      tags:
        - ItemVariants
      summary: Bulk restore ItemVariants by ids (atomic)
      operationId: bulkRestoreItemVariants
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemVariantBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/item_variants/restore/all:
    post:
      tags:
        - ItemVariants
      summary: Restore all soft-deleted ItemVariants
      operationId: restoreAllItemVariants
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/catalog/item_variants/trash/bulk:
    delete:
      tags:
        - ItemVariants
      summary: Bulk permanently-delete ItemVariants from trash by ids (atomic)
      operationId: bulkPermanentDeleteItemVariants
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/uoms:
    get:
      tags:
        - Uoms
      summary: List Uoms
      description: Get a paginated list of Uoms with optional filtering and sorting
      operationId: listUoms
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UomList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - Uoms
      summary: Create Uom
      description: Create a new Uom
      operationId: createUom
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUomRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Uom'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/catalog/uoms/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - Uoms
      summary: Get Uom by ID
      operationId: getUom
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Uom'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - Uoms
      summary: Update Uom (full)
      operationId: updateUom
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUomRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Uom'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - Uoms
      summary: Update Uom (partial)
      operationId: patchUom
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchUomRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Uom'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - Uoms
      summary: Delete Uom (soft)
      operationId: deleteUom
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/catalog/uoms/bulk:
    post:
      tags:
        - Uoms
      summary: Bulk create Uoms
      operationId: bulkCreateUoms
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateUomRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Uom'
    put:
      tags:
        - Uoms
      summary: Bulk update Uoms (full, atomic)
      operationId: bulkUpdateUoms
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateUomRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UomBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - Uoms
      summary: Bulk partial-update Uoms (atomic)
      operationId: bulkPatchUoms
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UomBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/uoms/upsert:
    post:
      tags:
        - Uoms
      summary: Upsert Uom
      operationId: upsertUom
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUomRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Uom'

  /api/v1/catalog/uoms/trash:
    get:
      tags:
        - Uoms
      summary: List deleted Uoms
      operationId: listDeletedUoms
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UomList'

  /api/v1/catalog/uoms/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - Uoms
      summary: Restore deleted Uom
      operationId: restoreUom
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Uom'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/catalog/uoms/empty:
    delete:
      tags:
        - Uoms
      summary: Empty trash for Uoms
      operationId: emptyTrashUoms
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/catalog/uoms/delete/bulk:
    post:
      tags:
        - Uoms
      summary: Bulk soft-delete Uoms by ids (atomic)
      operationId: bulkDeleteUoms
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/uoms/restore/bulk:
    post:
      tags:
        - Uoms
      summary: Bulk restore Uoms by ids (atomic)
      operationId: bulkRestoreUoms
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UomBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/uoms/restore/all:
    post:
      tags:
        - Uoms
      summary: Restore all soft-deleted Uoms
      operationId: restoreAllUoms
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/catalog/uoms/trash/bulk:
    delete:
      tags:
        - Uoms
      summary: Bulk permanently-delete Uoms from trash by ids (atomic)
      operationId: bulkPermanentDeleteUoms
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/uom_conversions:
    get:
      tags:
        - UomConversions
      summary: List UomConversions
      description: Get a paginated list of UomConversions with optional filtering and sorting
      operationId: listUomConversions
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UomConversionList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - UomConversions
      summary: Create UomConversion
      description: Create a new UomConversion
      operationId: createUomConversion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUomConversionRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UomConversion'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/catalog/uom_conversions/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - UomConversions
      summary: Get UomConversion by ID
      operationId: getUomConversion
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UomConversion'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - UomConversions
      summary: Update UomConversion (full)
      operationId: updateUomConversion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUomConversionRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UomConversion'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - UomConversions
      summary: Update UomConversion (partial)
      operationId: patchUomConversion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchUomConversionRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UomConversion'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - UomConversions
      summary: Delete UomConversion (soft)
      operationId: deleteUomConversion
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/catalog/uom_conversions/bulk:
    post:
      tags:
        - UomConversions
      summary: Bulk create UomConversions
      operationId: bulkCreateUomConversions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateUomConversionRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UomConversion'
    put:
      tags:
        - UomConversions
      summary: Bulk update UomConversions (full, atomic)
      operationId: bulkUpdateUomConversions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateUomConversionRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UomConversionBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - UomConversions
      summary: Bulk partial-update UomConversions (atomic)
      operationId: bulkPatchUomConversions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UomConversionBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/uom_conversions/upsert:
    post:
      tags:
        - UomConversions
      summary: Upsert UomConversion
      operationId: upsertUomConversion
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUomConversionRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UomConversion'

  /api/v1/catalog/uom_conversions/trash:
    get:
      tags:
        - UomConversions
      summary: List deleted UomConversions
      operationId: listDeletedUomConversions
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UomConversionList'

  /api/v1/catalog/uom_conversions/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - UomConversions
      summary: Restore deleted UomConversion
      operationId: restoreUomConversion
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UomConversion'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/catalog/uom_conversions/empty:
    delete:
      tags:
        - UomConversions
      summary: Empty trash for UomConversions
      operationId: emptyTrashUomConversions
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/catalog/uom_conversions/delete/bulk:
    post:
      tags:
        - UomConversions
      summary: Bulk soft-delete UomConversions by ids (atomic)
      operationId: bulkDeleteUomConversions
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/uom_conversions/restore/bulk:
    post:
      tags:
        - UomConversions
      summary: Bulk restore UomConversions by ids (atomic)
      operationId: bulkRestoreUomConversions
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UomConversionBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/catalog/uom_conversions/restore/all:
    post:
      tags:
        - UomConversions
      summary: Restore all soft-deleted UomConversions
      operationId: restoreAllUomConversions
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/catalog/uom_conversions/trash/bulk:
    delete:
      tags:
        - UomConversions
      summary: Bulk permanently-delete UomConversions from trash by ids (atomic)
      operationId: bulkPermanentDeleteUomConversions
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

components:
  schemas:
    Attribute:
      type: object
      required:
        - id
        - code
        - name
        - attribute_type
        - status
        - metadata
      properties:
        id:
          type: string
          format: uuid
        code:
          type: string
          maxLength: 40
        name:
          type: string
          maxLength: 100
        attribute_type:
          type: string
        status:
          type: string
        metadata:
          type: object

    AttributeBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Attribute'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateAttributeRequest:
      type: object
      required:
        - code
        - name
        - attribute_type
        - status
        - metadata
      properties:
        code:
          type: string
          maxLength: 40
        name:
          type: string
          maxLength: 100
        attribute_type:
          type: string
        status:
          type: string
        metadata:
          type: object

    UpdateAttributeRequest:
      type: object
      required:
        - code
        - name
        - attribute_type
        - status
        - metadata
      properties:
        code:
          type: string
          maxLength: 40
        name:
          type: string
          maxLength: 100
        attribute_type:
          type: string
        status:
          type: string
        metadata:
          type: object

    PatchAttributeRequest:
      type: object
      properties:
        code:
          type: string
          maxLength: 40
        name:
          type: string
          maxLength: 100
        attribute_type:
          type: string
        status:
          type: string
        metadata:
          type: object

    AttributeList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Attribute'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    AttributeValue:
      type: object
      required:
        - id
        - attribute_id
        - code
        - label
        - sort_order
        - status
        - metadata
      properties:
        id:
          type: string
          format: uuid
        attribute_id:
          type: string
          format: uuid
        code:
          type: string
          maxLength: 40
        label:
          type: string
          maxLength: 100
        label_en:
          nullable: true
          type: string
          maxLength: 100
        swatch_hex:
          nullable: true
          type: string
          maxLength: 10
        icon:
          nullable: true
          type: string
          maxLength: 255
        sort_order:
          type: integer
          format: int32
        status:
          type: string
        metadata:
          type: object

    AttributeValueBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AttributeValue'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateAttributeValueRequest:
      type: object
      required:
        - attribute_id
        - code
        - label
        - sort_order
        - status
        - metadata
      properties:
        attribute_id:
          type: string
          format: uuid
        code:
          type: string
          maxLength: 40
        label:
          type: string
          maxLength: 100
        label_en:
          nullable: true
          type: string
          maxLength: 100
        swatch_hex:
          nullable: true
          type: string
          maxLength: 10
        icon:
          nullable: true
          type: string
          maxLength: 255
        sort_order:
          type: integer
          format: int32
        status:
          type: string
        metadata:
          type: object

    UpdateAttributeValueRequest:
      type: object
      required:
        - attribute_id
        - code
        - label
        - sort_order
        - status
        - metadata
      properties:
        attribute_id:
          type: string
          format: uuid
        code:
          type: string
          maxLength: 40
        label:
          type: string
          maxLength: 100
        label_en:
          nullable: true
          type: string
          maxLength: 100
        swatch_hex:
          nullable: true
          type: string
          maxLength: 10
        icon:
          nullable: true
          type: string
          maxLength: 255
        sort_order:
          type: integer
          format: int32
        status:
          type: string
        metadata:
          type: object

    PatchAttributeValueRequest:
      type: object
      properties:
        attribute_id:
          type: string
          format: uuid
        code:
          type: string
          maxLength: 40
        label:
          type: string
          maxLength: 100
        label_en:
          nullable: true
          type: string
          maxLength: 100
        swatch_hex:
          nullable: true
          type: string
          maxLength: 10
        icon:
          nullable: true
          type: string
          maxLength: 255
        sort_order:
          type: integer
          format: int32
        status:
          type: string
        metadata:
          type: object

    AttributeValueList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AttributeValue'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    Brand:
      type: object
      required:
        - id
        - code
        - name
        - sort_order
        - status
        - metadata
      properties:
        id:
          type: string
          format: uuid
        code:
          type: string
          maxLength: 40
        name:
          type: string
          maxLength: 150
        short_description:
          nullable: true
          type: string
          maxLength: 500
        description:
          nullable: true
          type: string
          maxLength: 2000
        logo_url:
          nullable: true
          type: string
          maxLength: 500
        sort_order:
          type: integer
          format: int32
        status:
          type: string
        metadata:
          type: object

    BrandBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Brand'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateBrandRequest:
      type: object
      required:
        - code
        - name
        - sort_order
        - status
        - metadata
      properties:
        code:
          type: string
          maxLength: 40
        name:
          type: string
          maxLength: 150
        short_description:
          nullable: true
          type: string
          maxLength: 500
        description:
          nullable: true
          type: string
          maxLength: 2000
        logo_url:
          nullable: true
          type: string
          maxLength: 500
        sort_order:
          type: integer
          format: int32
        status:
          type: string
        metadata:
          type: object

    UpdateBrandRequest:
      type: object
      required:
        - code
        - name
        - sort_order
        - status
        - metadata
      properties:
        code:
          type: string
          maxLength: 40
        name:
          type: string
          maxLength: 150
        short_description:
          nullable: true
          type: string
          maxLength: 500
        description:
          nullable: true
          type: string
          maxLength: 2000
        logo_url:
          nullable: true
          type: string
          maxLength: 500
        sort_order:
          type: integer
          format: int32
        status:
          type: string
        metadata:
          type: object

    PatchBrandRequest:
      type: object
      properties:
        code:
          type: string
          maxLength: 40
        name:
          type: string
          maxLength: 150
        short_description:
          nullable: true
          type: string
          maxLength: 500
        description:
          nullable: true
          type: string
          maxLength: 2000
        logo_url:
          nullable: true
          type: string
          maxLength: 500
        sort_order:
          type: integer
          format: int32
        status:
          type: string
        metadata:
          type: object

    BrandList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Brand'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    Item:
      type: object
      required:
        - id
        - item_code
        - name
        - item_group_id
        - default_uom_id
        - item_type
        - is_sales_item
        - is_purchase_item
        - is_stock_item
        - has_variants
        - is_taxable
        - tags
        - data
        - status
        - metadata
      properties:
        id:
          type: string
          format: uuid
        item_code:
          type: string
          maxLength: 60
        name:
          type: string
          maxLength: 200
        description:
          nullable: true
          type: string
          maxLength: 2000
        barcode:
          nullable: true
          type: string
          maxLength: 60
        brand_id:
          nullable: true
          type: string
          format: uuid
        item_group_id:
          type: string
          format: uuid
        default_uom_id:
          type: string
          format: uuid
        item_type:
          type: string
        is_sales_item:
          type: boolean
        is_purchase_item:
          type: boolean
        is_stock_item:
          type: boolean
        has_variants:
          type: boolean
        hsn_code:
          nullable: true
          type: string
          maxLength: 20
        sni:
          nullable: true
          type: string
          maxLength: 30
        is_taxable:
          type: boolean
        weight_per_unit:
          nullable: true
          type: string
        shelf_life_days:
          nullable: true
          type: integer
          format: int32
        standard_cost:
          nullable: true
          type: string
        tags:
          type: object
        data:
          type: object
        status:
          type: string
        metadata:
          type: object

    ItemBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateItemRequest:
      type: object
      required:
        - item_code
        - name
        - item_group_id
        - default_uom_id
        - item_type
        - is_sales_item
        - is_purchase_item
        - is_stock_item
        - has_variants
        - is_taxable
        - tags
        - data
        - status
        - metadata
      properties:
        item_code:
          type: string
          maxLength: 60
        name:
          type: string
          maxLength: 200
        description:
          nullable: true
          type: string
          maxLength: 2000
        barcode:
          nullable: true
          type: string
          maxLength: 60
        brand_id:
          nullable: true
          type: string
          format: uuid
        item_group_id:
          type: string
          format: uuid
        default_uom_id:
          type: string
          format: uuid
        item_type:
          type: string
        is_sales_item:
          type: boolean
        is_purchase_item:
          type: boolean
        is_stock_item:
          type: boolean
        has_variants:
          type: boolean
        hsn_code:
          nullable: true
          type: string
          maxLength: 20
        sni:
          nullable: true
          type: string
          maxLength: 30
        is_taxable:
          type: boolean
        weight_per_unit:
          nullable: true
          type: string
        shelf_life_days:
          nullable: true
          type: integer
          format: int32
        standard_cost:
          nullable: true
          type: string
        tags:
          type: object
        data:
          type: object
        status:
          type: string
        metadata:
          type: object

    UpdateItemRequest:
      type: object
      required:
        - item_code
        - name
        - item_group_id
        - default_uom_id
        - item_type
        - is_sales_item
        - is_purchase_item
        - is_stock_item
        - has_variants
        - is_taxable
        - tags
        - data
        - status
        - metadata
      properties:
        item_code:
          type: string
          maxLength: 60
        name:
          type: string
          maxLength: 200
        description:
          nullable: true
          type: string
          maxLength: 2000
        barcode:
          nullable: true
          type: string
          maxLength: 60
        brand_id:
          nullable: true
          type: string
          format: uuid
        item_group_id:
          type: string
          format: uuid
        default_uom_id:
          type: string
          format: uuid
        item_type:
          type: string
        is_sales_item:
          type: boolean
        is_purchase_item:
          type: boolean
        is_stock_item:
          type: boolean
        has_variants:
          type: boolean
        hsn_code:
          nullable: true
          type: string
          maxLength: 20
        sni:
          nullable: true
          type: string
          maxLength: 30
        is_taxable:
          type: boolean
        weight_per_unit:
          nullable: true
          type: string
        shelf_life_days:
          nullable: true
          type: integer
          format: int32
        standard_cost:
          nullable: true
          type: string
        tags:
          type: object
        data:
          type: object
        status:
          type: string
        metadata:
          type: object

    PatchItemRequest:
      type: object
      properties:
        item_code:
          type: string
          maxLength: 60
        name:
          type: string
          maxLength: 200
        description:
          nullable: true
          type: string
          maxLength: 2000
        barcode:
          nullable: true
          type: string
          maxLength: 60
        brand_id:
          nullable: true
          type: string
          format: uuid
        item_group_id:
          type: string
          format: uuid
        default_uom_id:
          type: string
          format: uuid
        item_type:
          type: string
        is_sales_item:
          type: boolean
        is_purchase_item:
          type: boolean
        is_stock_item:
          type: boolean
        has_variants:
          type: boolean
        hsn_code:
          nullable: true
          type: string
          maxLength: 20
        sni:
          nullable: true
          type: string
          maxLength: 30
        is_taxable:
          type: boolean
        weight_per_unit:
          nullable: true
          type: string
        shelf_life_days:
          nullable: true
          type: integer
          format: int32
        standard_cost:
          nullable: true
          type: string
        tags:
          type: object
        data:
          type: object
        status:
          type: string
        metadata:
          type: object

    ItemList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    ItemGroup:
      type: object
      required:
        - id
        - code
        - name
        - is_group
        - level
        - sort_order
        - status
        - metadata
      properties:
        id:
          type: string
          format: uuid
        code:
          type: string
          maxLength: 40
        name:
          type: string
          maxLength: 150
        parent_id:
          nullable: true
          type: string
          format: uuid
        is_group:
          type: boolean
        level:
          type: integer
          format: int32
        sort_order:
          type: integer
          format: int32
        status:
          type: string
        metadata:
          type: object

    ItemGroupBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ItemGroup'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateItemGroupRequest:
      type: object
      required:
        - code
        - name
        - is_group
        - level
        - sort_order
        - status
        - metadata
      properties:
        code:
          type: string
          maxLength: 40
        name:
          type: string
          maxLength: 150
        parent_id:
          nullable: true
          type: string
          format: uuid
        is_group:
          type: boolean
        level:
          type: integer
          format: int32
        sort_order:
          type: integer
          format: int32
        status:
          type: string
        metadata:
          type: object

    UpdateItemGroupRequest:
      type: object
      required:
        - code
        - name
        - is_group
        - level
        - sort_order
        - status
        - metadata
      properties:
        code:
          type: string
          maxLength: 40
        name:
          type: string
          maxLength: 150
        parent_id:
          nullable: true
          type: string
          format: uuid
        is_group:
          type: boolean
        level:
          type: integer
          format: int32
        sort_order:
          type: integer
          format: int32
        status:
          type: string
        metadata:
          type: object

    PatchItemGroupRequest:
      type: object
      properties:
        code:
          type: string
          maxLength: 40
        name:
          type: string
          maxLength: 150
        parent_id:
          nullable: true
          type: string
          format: uuid
        is_group:
          type: boolean
        level:
          type: integer
          format: int32
        sort_order:
          type: integer
          format: int32
        status:
          type: string
        metadata:
          type: object

    ItemGroupList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ItemGroup'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    ItemVariant:
      type: object
      required:
        - id
        - item_id
        - sku
        - variant_label
        - options
        - is_default
        - status
        - metadata
      properties:
        id:
          type: string
          format: uuid
        item_id:
          type: string
          format: uuid
        sku:
          type: string
          maxLength: 60
        variant_label:
          type: string
          maxLength: 200
        options:
          type: object
        barcode:
          nullable: true
          type: string
          maxLength: 60
        is_default:
          type: boolean
        weight_per_unit:
          nullable: true
          type: string
        status:
          type: string
        metadata:
          type: object

    ItemVariantBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ItemVariant'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateItemVariantRequest:
      type: object
      required:
        - item_id
        - sku
        - variant_label
        - options
        - is_default
        - status
        - metadata
      properties:
        item_id:
          type: string
          format: uuid
        sku:
          type: string
          maxLength: 60
        variant_label:
          type: string
          maxLength: 200
        options:
          type: object
        barcode:
          nullable: true
          type: string
          maxLength: 60
        is_default:
          type: boolean
        weight_per_unit:
          nullable: true
          type: string
        status:
          type: string
        metadata:
          type: object

    UpdateItemVariantRequest:
      type: object
      required:
        - item_id
        - sku
        - variant_label
        - options
        - is_default
        - status
        - metadata
      properties:
        item_id:
          type: string
          format: uuid
        sku:
          type: string
          maxLength: 60
        variant_label:
          type: string
          maxLength: 200
        options:
          type: object
        barcode:
          nullable: true
          type: string
          maxLength: 60
        is_default:
          type: boolean
        weight_per_unit:
          nullable: true
          type: string
        status:
          type: string
        metadata:
          type: object

    PatchItemVariantRequest:
      type: object
      properties:
        item_id:
          type: string
          format: uuid
        sku:
          type: string
          maxLength: 60
        variant_label:
          type: string
          maxLength: 200
        options:
          type: object
        barcode:
          nullable: true
          type: string
          maxLength: 60
        is_default:
          type: boolean
        weight_per_unit:
          nullable: true
          type: string
        status:
          type: string
        metadata:
          type: object

    ItemVariantList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ItemVariant'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    Uom:
      type: object
      required:
        - id
        - code
        - name
        - uom_type
        - decimal_places
        - factor
        - is_protected
        - status
        - metadata
      properties:
        id:
          type: string
          format: uuid
        code:
          type: string
          maxLength: 20
        name:
          type: string
          maxLength: 80
        uom_type:
          type: string
        decimal_places:
          type: integer
          format: int32
          minimum: 0
          maximum: 6
        relative_uom_id:
          nullable: true
          type: string
          format: uuid
        relative_factor:
          nullable: true
          type: string
        factor:
          type: string
        is_protected:
          type: boolean
        status:
          type: string
        metadata:
          type: object

    UomBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Uom'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateUomRequest:
      type: object
      required:
        - code
        - name
        - uom_type
        - decimal_places
        - factor
        - is_protected
        - status
        - metadata
      properties:
        code:
          type: string
          maxLength: 20
        name:
          type: string
          maxLength: 80
        uom_type:
          type: string
        decimal_places:
          type: integer
          format: int32
          minimum: 0
          maximum: 6
        relative_uom_id:
          nullable: true
          type: string
          format: uuid
        relative_factor:
          nullable: true
          type: string
        factor:
          type: string
        is_protected:
          type: boolean
        status:
          type: string
        metadata:
          type: object

    UpdateUomRequest:
      type: object
      required:
        - code
        - name
        - uom_type
        - decimal_places
        - factor
        - is_protected
        - status
        - metadata
      properties:
        code:
          type: string
          maxLength: 20
        name:
          type: string
          maxLength: 80
        uom_type:
          type: string
        decimal_places:
          type: integer
          format: int32
          minimum: 0
          maximum: 6
        relative_uom_id:
          nullable: true
          type: string
          format: uuid
        relative_factor:
          nullable: true
          type: string
        factor:
          type: string
        is_protected:
          type: boolean
        status:
          type: string
        metadata:
          type: object

    PatchUomRequest:
      type: object
      properties:
        code:
          type: string
          maxLength: 20
        name:
          type: string
          maxLength: 80
        uom_type:
          type: string
        decimal_places:
          type: integer
          format: int32
          minimum: 0
          maximum: 6
        relative_uom_id:
          nullable: true
          type: string
          format: uuid
        relative_factor:
          nullable: true
          type: string
        factor:
          type: string
        is_protected:
          type: boolean
        status:
          type: string
        metadata:
          type: object

    UomList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Uom'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    UomConversion:
      type: object
      required:
        - id
        - from_uom_id
        - to_uom_id
        - factor
        - metadata
      properties:
        id:
          type: string
          format: uuid
        from_uom_id:
          type: string
          format: uuid
        to_uom_id:
          type: string
          format: uuid
        factor:
          type: string
        metadata:
          type: object

    UomConversionBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/UomConversion'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateUomConversionRequest:
      type: object
      required:
        - from_uom_id
        - to_uom_id
        - factor
        - metadata
      properties:
        from_uom_id:
          type: string
          format: uuid
        to_uom_id:
          type: string
          format: uuid
        factor:
          type: string
        metadata:
          type: object

    UpdateUomConversionRequest:
      type: object
      required:
        - from_uom_id
        - to_uom_id
        - factor
        - metadata
      properties:
        from_uom_id:
          type: string
          format: uuid
        to_uom_id:
          type: string
          format: uuid
        factor:
          type: string
        metadata:
          type: object

    PatchUomConversionRequest:
      type: object
      properties:
        from_uom_id:
          type: string
          format: uuid
        to_uom_id:
          type: string
          format: uuid
        factor:
          type: string
        metadata:
          type: object

    UomConversionList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/UomConversion'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
          example: 100
        page:
          type: integer
          example: 1
        per_page:
          type: integer
          example: 20
        total_pages:
          type: integer
          example: 5

    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: VALIDATION_ERROR
        message:
          type: string
          example: Invalid input data
        details:
          type: object
          additionalProperties: true

  parameters:
    IdParam:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid

    PageParam:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1

    PerPageParam:
      name: per_page
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20

    SortByParam:
      name: sort_by
      in: query
      schema:
        type: string

    SortOrderParam:
      name: sort_order
      in: query
      schema:
        type: string
        enum: [asc, desc]
        default: asc

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  requestBodies:
    BatchIds:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [ids]
            properties:
              ids:
                type: array
                items: { type: string }

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []