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.

.. gm:data:: schemaObject

   .. gm:data:: unique

      This is a list of attribute groups that should be unique. See below for
      examples.

   .. gm:data:: 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.

.. gm:data:: categoryObject

   .. gm:data:: clientCatalogId

      This is a string representing the id of the catalog this category belongs to.

   .. gm:data:: clientCategoryId

      This is a string representing the unique id of this category.

   .. gm:data:: description

      This is an optional string description of the category.

   .. gm:data:: schema

      This is a :ref:`Schema Object` that defines the schema that this category's
      products will follow.

   .. gm:data:: categoryAttributes

      This is an object which can hold arbitrary key-value pairs related to
      this category.

   .. gm:data:: 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