Overview

A schema establishes the properties of each attribute within a product catalog and determines the various functions and operations that can be supported for each attribute. For example, a numeric dataType will allow less than, greater than, and range facets, whereas a text dataType will support operations such as contains and support text facets.

---

Schema Formats

The schema is part of a larger JSON feed file and is defined by the “schema” node. Each JSON object within the schema represents a field within your catalog.

Each field must contain the following properties:

• fieldName (Mandatory)
• dataType (Mandatory)
• multiValued (Mandatory)
• autoSuggest (Mandatory)
• isVariant (Optional)
• id (Optional)

📘

Important Recommendation

While we recommend you upload both the schema and catalog as a unified JSON file, you can also upload the schema as a separate file.

fieldName

The fieldName specifies the name of the attribute such as title, color, and brand. Field names are case-sensitive; should start with an alphabet or underscore; can only contain alphanumeric characters, hyphens and underscores; cannot contain special characters, spaces, or end with an underscore.

id

The id in the schema specifies a numerical identifier for an attribute in the catalog. This is useful when product feeds may have the fieldID instead of the fieldName.

dataType

A dataType defines the type of value a specific field can have. We support the following dataTypes.

📘

Note

Data Types of fields that are made searchable display those products on the search results page. Data Types that are not searchable can be used for filtering, sorting, and faceting.

multiValued

A multiValued attribute determines if a field can have multiple values for a product.

For example, a Nike shoe can be considered sporty and casual, in which case you could send multiple values for a style field: “style”: [“casual” , ”sport”]. However, a field such as brand would be single-valued: “brand”:” Nike ”

To enable a field to accept multiple values, set multiValued to true; otherwise, it will be false.

isVariant

Only required for catalogs with variants, if an attribute is a variant field instead of a parent product field, set it to true or false.

---

Sample Schema

{
"feed": {
        "catalog": {
            "schema": [{
                "fieldName": "vColor",
                "id": "76678",
                "dataType": "text",
                "multiValued":true,
                "autoSuggest":false,
                "isVariant":true
            }, {
                "fieldName": "vSize",
                "dataType": "text",
                "multiValued":true,
                "autoSuggest":false,
                "isVariant":true
            }, {
                "fieldName": "vImages",
                "dataType": "link",
                "multiValued":true,
                "autoSuggest":false,
                "isVariant":true
            },
{
                "fieldName": "vPrice",
                "dataType": "decimal",
                "multiValued":true,
                "autoSuggest":false,
                "isVariant":true
            }]
        }
    }
}

---

Schema Upload Process

You can upload a schema using APIs, except instances where Unbxd performs any post-processing on your schema, which requires an SFTP upload. Every schema upload appends to an existing schema, if any. You can update the characteristics.

If the schema has fields already found within an existing schema, the property values of the existing fields are updated. Similarly, when the new schema has new fields not found within an existing schema, the existing schema appends and adds the new fields. It is currently not possible to delete existing fields through the schema API.

---

API Parameters

The API parameters, along with sample request and response are defined below:

• API Endpoint
  Method: POST End Point: \{feed end point}/\{siteKey}/upload/schema Description: This API will perform an upload/update of the schema file.
• Parameters
  • 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.
  • file: The schema's name, as a JSON file.
  • feed end point: The feed end point depends upon the region selected at site creation.
    • US region: http://feed.unbxd.io/
    • ANZ region : http://feed-anz.unbxd.io/
    • UK region : http://feed-uk.unbxd.io/
    • SG region : [http://feed-apac.unbxd.io/
• Error Codes
  We use conventional HTTP response codes to indicate the success or failure of an API request. 201 (Ok): This indicates the upload was successful. 401 (Authorization Error): You may have provided an invalid API key. 400 (Bad Request): You may have missed a required parameter. 500 (Internal Server Error): Though these are rare, this indicates we may have messed up.
• Sample Request

curl -X POST https\://\{Feed end point}/api/\{siteKey}/upload/schema\
-H 'Authorization:\{secretKey}'
-F file=\{file}

Best Practices

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

• Schema is required for all fields (except for internal fields created by Unbxd)
• 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 an alphabet or underscore. They can be alphanumeric, have hyphens, or underscores. They cannot contain special characters, spaces between words, or end with an underscore.
• Do not send fields that have null values.