Target Formats
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:
Name | Type | Properties | Description |
---|---|---|---|
TargetFormatSchema | Interface | id : stringtargetFormat : TargetFormatname? : stringjobs? : JobSchema[]default? : boolean | How a target format is stored in the database, with associated jobs and meta-information. |
TargetFormat | Interface | [key: string] : TargetFormatField | Defines the structure of the target format, with keys as field names and values as TargetFormatField objects |
TargetFormatField | Interface | type : ‘string’ | ‘number’ | ‘boolean’ | ‘array’description? : stringchoices? : string[]attributes? : TargetFieldAttribute[]fields? : TargetFormat | Defines the structure of a field in the target format |
TargetFieldAttribute | Enum | required 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.
Type | Description | Default Value |
---|---|---|
string | Represents textual data. Can be any sequence of characters. | "" (empty string) |
number | Represents numeric data. Includes integers and floating-point numbers. | 0 |
boolean | Represents a logical value. Can be either true or false. | false |
array | Represents 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.
Attribute | Compatible Types | Transformation Explanation |
---|---|---|
capitalized | string, array | Transforms the first letter of each word to uppercase. E.g., “hello world” becomes “Hello World”. |
wholeNumber | number | Rounds down to the nearest integer. E.g., 3.7 becomes 3. |
positiveNumber | number | Ensures the number is greater than 0. |
decimalNumber | number | Ensures the value is parsed as a float with 2 decimal places. |
email | string, array | Validates the string as an email address and normalizes format (lowercase, trim whitespace). |
url | string, array | Validates and normalizes URL format, adds “https://” if missing. |
phoneNumber | string, array | Formats phone number to a standard format, e.g., (xxx) xxx-xxxx in the US. |
date | string, array | Parses various date formats into a standard date format: YYYY-MM-DD. |
time | string, array | Parses various time formats into a standard time format: HH:MM:SS. |
datetime | string, array | Combines date and time parsing, outputting a standard format: YYYY-MM-DDTHH:MM:SS. |
currency | string, array | Converts string to 3 letter currency code. E.g. dollar, usd $ => USD. |
percentage | string, array | Converts 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:
Attribute | Compatible Types | Transformation Explanation |
---|---|---|
required | string, number, boolean, array | Ensures a non-null, non-empty value is provided. If no value is provided, the field will be skipped during indexing. |
primary | string, number, boolean, array | Defines 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. |
indexProductID | string | Special 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. |
embedText | string, array | Uses 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. |
embedImage | string, array | Uses 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.