Docs

Prepare Schema

Every Product attribute must have a predefined schema that helps us understand your product better.

On this page, we define a schema and its components, how you can send your updated schema file to us and some practices we recommend you follow while prepping your schema for upload.

Overview

A schema is a key component of a product catalog. It contains definitions of all fields used within your catalog.

Every field which is part of the product must be defined with its associated property. This is defined under schema component.

Sample Schema
{
  "feed": {
    "catalog": {
      "schema": [
        {
          "fieldName": "color",
          "dataType": "text",
          "id": "76678",
          "multiValue": "true"
        },
        {
          "fieldName": "size",
          "dataType": "text",
          "id": "76679",
          "multiValue": "true"
        },
        {
          "fieldName": "images",
          "dataType": "link",
          "multiValue": "true"
        },
        {
          "fieldName": "price",
          "dataType": "decimal",
          "multiValue": "true"
        }
      ]
    }
  }
}

Components

Your product catalog contains a list of all your product and its attributes. A schema defines the properties of the attributes in your product catalog.

For instance, when your catalog has fields like 'title', 'size', 'price', and 'image', a schema file helps your search engine make sense of the information within such fields in the catalog. The schema establishes the properties of each attribute, determining the type of information the field will contain and display. A schema makes this possible by defining the attributes for 'title', 'size', 'price', and 'image'.

There are four properties that define a field in a schema:

  • dataType
  • fieldName
  • multiValue
  • id
While we recommend you upload both the schema and catalog as a unified JSON file, you can also upload just the schema file.

dataType

The dataType attribute of a value (also known as a variable) is an attribute that tells what kind of data that value can have.

Consider this analogy: A dataType is like a box that is designed to hold items only of specific characteristics.

We support the following nine dataTypes.

dataType Type DescriptionSearchable*
title String Used for fields that describe a product Yes
description-text String Used for fields that describe a product in detail Yes
decimal Decimal Used for fields that accept decimal values Yes
number Numeric Used for fields that accept number values -
link URL String Used for fields that accept URL strings as values -
date YYYY-MM-DD
HH:MM:SS
Used for fields that accept dates -
bool True/False Used for fields that accept boolean values -
nskuStringUsed for fields that denote unique information of the product such as skuid. Fields with this data type can be used in search queries.
We support partial search on "nsku" datatype.
Yes
facetStringUsed to filter products displayed in the Product Listing Page.
These fields will be stored as is and will not be processed for spelling, stemming, or tokenization.
-
sku String Used for fields that denote unique information of the product. Yes
path String Used for fields that are hierarchical in nature Values are separated by ‘>’ -

*Data Types that are searchable are available within the search results page. Data Types that are not searchable can be used for filtering, sorting, and faceting.

fieldName

The fieldName attribute specifies the name of the field.

Some examples of a fieldName are 'productURL', 'sku', 'color', 'brand' etc.

multiValue

A multiValue attribute determines if a field can take multiple values.

For example, when a shirt with one productID has two or more images (front/back) of the same shirt, then 'image' is a multiValue attribute.

To enable a field to accept multiple values, set multiValue to true. Else, false.

A multiValue attribute describes multiple attributes (different images etc) for a field of the same product/sku, while a variant describes different products with varying attributes (size/color/material) which can be grouped together. Both of these attributes help your shopper make an informed purchase decision.

id

The id attribute specifies the numerical identifier of a field, when available.
Product feeds may have a fieldID instead of the fieldName.

Upload

This API allows you to upload your schema.

A feed must have both the catalog and the schema file. If you've already uploaded a schema previously, use this API to upload only the updated schema.

In case the schema has updated values for fields that already exist, the fields are updated. New fields, if any, are added to the existing schema file.

API Query

Post: /{siteKey}/upload/schema

Description

This API will perform a full upload of just the schema file.

Parameters

Parameters in the API query are:

  • siteKey : A unique identifier provided when your Unbxd account is created. This key can also be retrieved from your Unbxd Console. This is a required field.
  • secretKey : A unique identifier provided when your Unbxd account is created. The secretKey is used to authorize your upload request. This is a private key and will not be exposed to the public. This is a required field.
  • fileName : The name of the schema, as a JSON file.
Errors

We use conventional HTTP response codes to indicate success or failure of an API request.

  • 201 (Ok): Indicates the upload was successful.
  • 401 (Authorization Error): Indicates you may have provided an invalid API key.
  • 400 (Bad Request): Indicates you may have missed a required parameter.
  • 500 (Internal Server Error): Though these are rare, this indicates we may have messed up.

Best Practices

To ensure your schema is uploaded and integrated seamlessly, here are some practices we recommend:

  • Define your schema right in the beginning. Unbxd-defined schemas are called Featured Fields.
  • Schemas not adequately defined will be rejected.
  • Ensure your schema file is in JSON format.
  • Field names are case-sensitive.
  • Field names should start with alphabets or underscore. It can be alphanumeric, can have hyphens and underscores. It cannot contain special characters, spaces in between words, or end with an underscore.

Next Steps