Target Formats define the structure and validation rules for your product data. They ensure consistency and data quality across different sources and can be used for data validation and transformation.

​
Target Format Schema

A Target Format is stored as TargetFormatSchema, which is composed of meta-information as well as fields, each with its own set of properties:

NameTypePropertiesDescription
TargetFormatSchemaInterfaceid: string
targetFormat: TargetFormat
name?: string
jobs?: JobSchema[]
default?: boolean		How a target format is stored in the database, with associated jobs and meta-information.
TargetFormatInterface[key: string]: TargetFormatFieldDefines the structure of the target format, with keys as field names and values as TargetFormatField objects
TargetFormatFieldInterfacetype: ‘string’ | ‘number’ | ‘boolean’ | ‘array’
description?: string
choices?: string[]
attributes?: TargetFieldAttribute[]
fields?: TargetFormat		Defines the structure of a field in the target format
TargetFieldAttributeEnumrequired
capitalized
wholeNumber
positiveNumber
decimalNumber
email
url
phoneNumber
date
time
datetime
currency
percentage
primary
indexProductID
embedText
embedImage		Enum of possible attributes for a target field

For each field, you can specify the type of data it will contain, along with any additional attributes or constraints.

TypeDescriptionDefault Value
stringRepresents textual data. Can be any sequence of characters."" (empty string)
numberRepresents numeric data. Includes integers and floating-point numbers.0
booleanRepresents a logical value. Can be either true or false.false
arrayRepresents a list or collection of values. Can contain elements of any type.[] (empty array)

index provides a list of attributes that can be used to further customize the target field and specify formatting and validation rules.

AttributeCompatible TypesTransformation Explanation
capitalizedstring, arrayTransforms the first letter of each word to uppercase. E.g., “hello world” becomes “Hello World”.
wholeNumbernumberRounds down to the nearest integer. E.g., 3.7 becomes 3.
positiveNumbernumberEnsures the number is greater than 0.
decimalNumbernumberEnsures the value is parsed as a float with 2 decimal places.
emailstring, arrayValidates the string as an email address and normalizes format (lowercase, trim whitespace).
urlstring, arrayValidates and normalizes URL format, adds “https://” if missing.
phoneNumberstring, arrayFormats phone number to a standard format, e.g., (xxx) xxx-xxxx in the US.
datestring, arrayParses various date formats into a standard date format: YYYY-MM-DD.
timestring, arrayParses various time formats into a standard time format: HH:MM:SS.
datetimestring, arrayCombines date and time parsing, outputting a standard format: YYYY-MM-DDTHH:MM:SS.
currencystring, arrayConverts string to 3 letter currency code. E.g. dollar, usd $ => USD.
percentagestring, arrayConverts decimal to percentage or ensures correct format, e.g., 0.5 to 50% or 50 to 50%. Must be used with types string or array.

index also specifies the following special attributes that are used to handle the indexing process:

AttributeCompatible TypesTransformation Explanation
requiredstring, number, boolean, arrayEnsures a non-null, non-empty value is provided. If no value is provided, the field will be skipped during indexing.
primarystring, number, boolean, arrayDefines the field as the primary index that is used to match during updates. This will be used to create the row id. You can define multiple fields as primary. During updates, if all of a new row’s primary fields are equal to an existing row, it will update the existing row. It is best practice to apply primary to the indexProductId and the product link fields to get the best results.
indexProductIDstringSpecial flag that leverages the index product grouper. Fills the field with a unique and product id provided by index that is persistent across merchants and sources.
embedTextstring, arrayUses the specified field to create an embedding from the field content. At least one embedText or embedText is required if you want to use semantic search.
embedImagestring, arrayUses the specified field to create an image embedding from the field content. Field content needs to be a URL that points to an image. At least one of the flags is required if you want to use semantic search.

​
Target Format Operations

​
Query: getTargetFormats

Retrieves all saved target formats.

getTargetFormats: [TargetFormatSchema!]

​
Example:

query {
  getTargetFormats {
    id
    name
    targetFormat
    default
    jobs {
      id
      status
    }
  }
}

​
Response:

{
  "data": {
    "getTargetFormats": [
      {
        "id": "453",
        "name": "Standard Product Format",
        "targetFormat": {
          "Name": {
            "type": "string",
            "attributes": ["required", "capitalized", "primary"]
          },
          "Brand": {
            "type": "string",
            "attributes": ["required", "capitalized", "primary"]
          },
          "Link": {
            "type": "string",
            "attributes": ["required", "url", "primary"]
          },
          "Status": {
            "type": "string",
            "description": "Current status of the product (e.g., active, draft, archived)",
            "attributes": ["required"],
            "choices": ["active", "draft", "archived"]
          },
          "Gift Card": {
            "type": "boolean",
            "description": "Indicates if the product is a gift card (TRUE/FALSE)",
            "attributes": ["required"]
          },
          "Image Src": {
            "type": "array",
            "description": "URLs of the product images",
            "attributes": ["url"]
          },
        },
        "default": true,
        "jobs": [
          {
            "id": "job1",
            "status": "Live"
          }
        ]
      }
    ]
  }
}

​
Mutation: saveTargetFormat

Saves a new target format.

saveTargetFormat(name: String, targetFormat: [JSON!]!, makeDefault: Boolean): ID

​
Example:

mutation {
  saveTargetFormat(
    name: "Extended Product Format",
    targetFormat: [
      {
        "Name": {
          "type": "string",
          "description": "Product name",
          "attributes": ["required", "capitalized"]
        },
        "Price": {
          "type": "number",
          "description": "Product price",
          "attributes": ["required", "positiveNumber", "currency"]
        },
        "Description": {
          "type": "string",
          "description": "Product description"
        },
        "Category": {
          "type": "string",
          "description": "Product category",
          "attributes": ["required"]
        },
        "Stock": {
          "type": "number",
          "description": "Current stock quantity",
          "attributes": ["required", "wholeNumber"]
        },
        "Rating": {
          "type": "number",
          "description": "Product rating (0-5)",
          "attributes": ["decimalNumber"]
        },
        "Launch Date": {
          "type": "string",
          "description": "Product launch date",
          "attributes": ["date"]
        }
      }
    ],
    makeDefault: false
  )
}

​
Response:

{
  "data": {
    "saveTargetFormat": "54" // ID of the newly created target format
  }
}

​
Mutation: deleteTargetFormat

Deletes a saved target format.

deleteTargetFormat(id: ID!): Boolean!

​
Example:

mutation {
  deleteTargetFormat(id: "54")
}

​
Response:

{
  "data": {
    "deleteTargetFormat": true
  }
}

​
Mutation: setDefaultTargetFormat

Sets a target format as the default.

setDefaultTargetFormat(id: ID!): Boolean!

​
Example:

mutation {
  setDefaultTargetFormat(id: "54")
}

​
Response:

{
  "data": {
    "setDefaultTargetFormat": true // whether the target format was set as default successfully
  }
}

​
Validation Using Target Formats

Target Formats can be used to validate product data, ensuring it meets the specified structure and rules. For detailed information on product validation, please refer to Product Validation.

Data SourcesProduct Validation