Category Management
*******************

A category is a way of defining common schema (and optionally, attribute values)
for a group of products instead of having to define them at a product level.

Defining a category for products is not mandatory, but recommended.

Schema Object
=============

A schema object defines the schema to be followed by a product or a category.
This puts restrictions on possible values of the attributes. For example, in a
schema, you may want to keep ``product_sku`` as unique for all products in a
category.

.. list-table:: **Attributes**
   :widths: 30, 70
   :header-rows: 0

   * - unique
     - This is a list of attribute groups that should be unique. See below for
       examples.
   * - type
     - This is a string with a constant value ``"object"``.

Examples of schema
------------------

1. ``product_sku`` should be unique

  .. code-block:: json
     
      {
          "unique": [
              ["product_sku"]
          ],
          "type": "object"
      }

2. Combination of ``product_sku`` and ``client_id`` should be unique

   .. code-block:: json
   
       {
           "unique": [
               [
                   "product_sku",
                   "client_id"
               ]
           ],
           "type": "object"
       }

3. Combination of ``product_sku`` and ``client_id`` should be unique and
   ``ql_code`` should also be unique

   .. code-block:: json
   
       {
           "unique": [
               [
                   "product_sku",
                   "client_id"
               ],
               [
                   "ql_code"
               ]
           ],
           "type": "object"
       }

Category Object
===============

Catagory object represents the schema and common attributes for all products
defined under that category.

.. list-table:: **Attributes**
   :widths: 30, 70
   :header-rows: 0

   * - clientCatalogId
     - This is a string representing the id of the catalog this category
       belongs to.
   * - clientCategoryId
     - This is a string representing the unique id of this category.
   * - description
     - This is an optional string description of the category.
   * - schema
     - This is a :ref:`Schema Object` that defines the schema that this
       category's products will follow.
   * - categoryAttributes
     - This is an object which can hold arbitrary key-value pairs related to
       this category.
   * - | **attributes**
       | *optional*
     - This is an object which can hold arbitrary key-value pairs which will
       automatically copied down as attributes of the products under this
       category, unless overridden at the product level.

Category Sample JSON
--------------------

.. literalinclude:: category_object.json
   :language: JSON