Schema Configuration

The Schema settings allow you to customize the structure and generation rules for your product content. Your schema defines what content gets generated and how it should be structured, giving you fine-grained control over AI output.

How the Schema Works

The schema you build is converted into a JSON structure that tells the AI exactly what fields to generate. Each block you create becomes a field in the output, with your rules and attached assets guiding the generation.

Example: A “title” block becomes:

{
  "title": {
    "type": "string",
    "description": "Create a title that is 5-10 words. Include the product name if provided. Ensure the title is engaging and aligns with the Brand Tone of Voice. Use asset with IDs: 227"
  }
}

Understanding Blocks

Blocks are the building units of your product content schema. Each block defines a specific piece of content to be generated.

Block Components

Each block contains:

• Field Name: The identifier for this content piece (e.g., “title”, “description”)
• Output Name: The field name for any system output for this content piece (e.g., “shop_title”, “shop_description”)
• Assets: Writing knowledge assets attached to guide generation
• Rules: Specific natural language instructions for the AI
• Passthrough: Configuration options to allow input data to pass through merchi.ai without being altered
• Field Type: Configuration options for the output structure of the data

Common Block Types

Title Block

Purpose: Generate compelling, search-friendly product titles

Best Practice Rules:

- Create a title that is 5-10 words
- Include the product ID; if it's a name, incorporate it naturally rather than append/prepend
- Include the product name if provided in the input data
- Ensure the title is engaging and aligns with the Brand Tone of Voice
- Refine titles to be search-friendly and accurately represent the product

Recommended Assets: Brand Tone of Voice

Description Block

Purpose: Generate engaging product descriptions

Best Practice Rules:

- Write a description in maximum of 150 words, broken into 2 paragraphs with a line break
- Use the Stop Words & Phrases for guidance on writing style
- Where relevant and beneficial, include information on seasonal trends
- Use different approaches (direct description, occasion-focused, benefit-led, detail-first)
- Ensure the description aligns with the Brand Tone of Voice provided

Recommended Assets: Brand Tone of Voice, Stop Words & Phrases, Seasonal Trends

Attributes Block

Purpose: Extract and categorize product attributes

Field Type: Array of objects

Best Practice Rules:

- Create a list of attributes and values relevant to this product
- Select only relevant attributes that apply to the specific product
- Ensure attributes are accurate and not based on assumptions
- Only pick attribute categories from the list that are relevant

Recommended Assets: Attributes List

Taxonomy Block

Purpose: Categorize products into your hierarchy

Field Type: Array of strings

Best Practice Rules:

- List categories and sub-categories from the provided taxonomy
- Based on product image and label analysis, determine the most accurate category
- From the selected category, choose the most relevant subcategories

Recommended Assets: Taxonomy (JSON)

Key Features & Benefits Block

Purpose: Generate bullet-point highlights

Field Type: Array of strings

Best Practice Rules:

- Write 5 bullet points highlighting the item's key benefits and features
- Include fabric type from the garment label if available
- Where relevant, include information on seasonal trends
- Ensure features & benefits are engaging and align with tone requirements

Recommended Assets: Brand Tone of Voice, Seasonal Trends

Styling Advice Block

Purpose: Provide outfit and occasion suggestions

Field Type: Array of strings

Best Practice Rules:

- List 3-5 potential styling options or occasions for the item
- Where relevant, include information on seasonal trends
- Ensure style advice is engaging and aligns with tone requirements

Recommended Assets: Brand Tone of Voice, Seasonal Trends

Care Instructions Block

Purpose: Extract care information from labels

Field Type: Array of objects

Best Practice Rules:

- List care instructions extracted from product images or input data
- Do not populate this if care instructions are not visible in images or provided in input data
- Do not make up care instructions - only use verified information

Recommended Assets: None (image-based extraction)

Meta Title Block

Purpose: Generate SEO-optimized page titles

Best Practice Rules:

Structure in the following format:
"Buy [Product Title] from [Brand] Online | [Store Name]"
- Use proper case
- Keep under 60 characters for optimal search display

Meta Description Block

Purpose: Generate SEO meta descriptions

Best Practice Rules:

- Create an SEO-friendly meta description in 120-155 characters
- Include primary keywords naturally
- Add a call-to-action when appropriate

Image Metadata Block

Purpose: Generate SEO-friendly image names and alt text

Field Type: Array of objects

Best Practice Rules:

Provide SEO-friendly image name and alt text for each image in the order provided:
{
  "imageName": "SEO-friendly-image-name-use-dash-case",
  "imageAltTag": "SEO friendly alt tag use sentence case"
}

Standards Pack Blocks

If your account has one or more Standards Packs active, you can create schema blocks that capture the classification output directly. These blocks tell the AI to surface the matched class, category, or brick — and to extract the standardised attribute values that belong to it.

For each standard, classification and attributes should be separate blocks. This keeps field types clean, makes downstream data mapping simpler, and lets you include one without the other if needed.

ETIM — Classification Block

Purpose: Identify the matched ETIM Group and Class for the product

Field Type: Object

Recommended Assets to Lookup: ETIM Standards Pack

Best Practice Rules:

Using the ETIM Standards Pack, identify the most appropriate ETIM Class for this product.
Return the ETIM Group code, Group name, Class code, and Class name.
If no strong ETIM match exists, return null.

ETIM — Features Block

Purpose: Extract structured attribute values for the identified ETIM Class

Field Type: Array of objects

Recommended Assets to Lookup: ETIM Standards Pack

Best Practice Rules:

Using the identified ETIM Class from the ETIM Standards Pack, extract values for each
applicable ETIM Feature. Only include features where a value can be confidently
determined from the product images or input data. Do not guess.
Return each feature as { "feature_code": "...", "feature_name": "...", "value": "...", "unit": "..." }

Shopify Taxonomy — Category Block

Purpose: Map the product to the most specific Shopify Standard Product Taxonomy category

Field Type: Object

Recommended Assets to Lookup: Shopify Taxonomy

Best Practice Rules:

Using the Shopify Taxonomy, identify the most specific matching category for this product.
Return the full category path (e.g. "Apparel & Accessories > Clothing > Tops > T-Shirts")
and the category ID.
If no strong match exists, return the closest parent category.

Shopify Taxonomy — Attributes Block

Purpose: Extract category-specific attribute values aligned to the Shopify standard

Field Type: Array of objects

Recommended Assets to Lookup: Shopify Taxonomy

Best Practice Rules:

Using the matched Shopify Taxonomy category, extract values for each standard attribute
associated with that category (e.g. Material, Color, Size Format, Target Gender).
Only include attribute values that are clearly supported by the product data or images.
Do not populate attributes where the value cannot be determined with confidence.
Return each attribute as { "name": "...", "value": "..." }

GS1 GPC — Brick Block

Purpose: Classify the product to the correct GS1 GPC Brick within its full hierarchy

Field Type: Object

Recommended Assets to Lookup: GS1 GPC

Best Practice Rules:

Using the GS1 GPC standard, identify the most appropriate GPC Brick for this product.
Return the full hierarchy: Segment name and code, Family name and code,
Class name and code, Brick name and code.
If no strong match exists, return null.

GS1 GPC — Attributes Block

Purpose: Extract GPC attribute type/value pairs for the identified Brick

Field Type: Array of objects

Recommended Assets to Lookup: GS1 GPC

Best Practice Rules:

Using the identified GPC Brick from the GS1 GPC standard, extract values for applicable
GPC Attribute Types. Use only values from the controlled value list defined for each
Attribute Type — do not invent values outside the defined set.
Only include Attribute Types where a value can be confidently determined.
Return each as { "attribute_type": "...", "attribute_value": "..." }

Google Product Taxonomy — Category Block

Purpose: Identify the closest Google Product Taxonomy category for feed and channel use

Field Type: Object

Recommended Assets to Lookup: Google Product Taxonomy

Note: Google taxonomy is classification-only — there is no attributes block for this standard.

Best Practice Rules:

Using the Google Product Taxonomy, identify the most specific matching category
for this product.
Return the numeric Google category ID and the full category path string
(e.g. "Apparel & Accessories > Clothing > Dresses").
If no strong match exists, return the closest parent category.

Adding a Block

1. Go to Settings > Schema
2. Click Add Block
3. Enter the Field Name
4. Select the Field Type (string, array, object)
5. Write your generation rules
6. Attach relevant assets
7. Save your changes

Attaching Assets

You can attach assets from your Writing Knowledge to specific blocks:

1. In the block editor, click Attach Asset
2. Select from your available assets
3. The asset content will be used when generating this block

Asset attachment best practices:

• Attach tone of voice to description, features, and styling blocks
• Attach stop words to all text-generation blocks
• Attach taxonomy only to categorization blocks
• Attach seasonal trends where context-aware content is needed

Using Standards Packs as Asset Lookups

If your account has Standards Packs enabled, they appear as a special option in the asset selector labelled Assets to use for Lookup. This is different from a regular asset attachment — instead of injecting a static document, the block is linked to a live classification database that is queried at processing time.

How to Attach a Standards Pack to a Block

1. Open the block editor for the block you want to configure
2. In the Assets to use for Lookup section, select the relevant standard (e.g. ETIM Standards Pack, Shopify Taxonomy, or GS1 GPC)
3. Write rules in the block that reference the standard by name and describe what you want extracted
4. Save the block

The asset lookup tells the AI which classification data to draw from when generating that block. The matched candidates (classes, categories, or bricks) are already injected into the prompt by the time the AI generates each field — the lookup in the block reinforces which standard is relevant for that specific field.

Standards Pack vs. Regular Assets

	Regular Asset	Standards Pack Lookup
Content	Static text, list, JSON, or table you maintain	Live classification database maintained by merchi.ai
Updates	You edit the asset manually	Updated centrally when new versions are released
Use case	Brand voice, attributes list, stop words, taxonomy	ETIM classes, Shopify categories, GS1 GPC bricks
How it works	Full content injected into the prompt	Top-matching candidates injected automatically at run time

Recommended Block Pairings

For each standard, use separate blocks for classification and attributes. This keeps the output structure clean and makes it easier to map individual fields downstream.

Standards Pack	Classification block	Attributes block
ETIM Standards Pack	etim_classification — Group and Class codes/names	etim_features — array of Feature code, name, value, unit
Shopify Taxonomy	shopify_category — full category path and ID	shopify_attributes — array of attribute name/value pairs
GS1 GPC	gpc_brick — full Segment > Family > Class > Brick hierarchy	gpc_attributes — array of Attribute Type/Value pairs
Google Product Taxonomy	google_taxonomy_category — numeric ID and full path string	None — classification only

For detailed guidance on writing rules for standards-based blocks, see the Standards Pack Blocks section above. For an overview of how Standards Packs work end-to-end, see Standards Packs.

Passthrough Fields

Some fields can be configured for “passthrough” - allowing input data to flow through without AI modification:

Best Practice Rules for Passthrough:

Using field name "[field_name]" passthrough here unless it's empty, then derive it based on [generation rules]

This is useful for:

• Product titles that should use provided names
• Descriptions that may already exist
• Care instructions from input data

Writing Effective Rules

Be Explicit About Constraints

Good: "Write a description in maximum of 150 words, broken into 2 paragraphs"
Bad: "Write a short description"

Specify Format Requirements

Good: "List 5 bullet points highlighting key features"
Bad: "Describe the features"

Reference Assets Clearly

Good: "Ensure the description aligns with the Brand Tone of Voice provided"
Bad: "Make it sound good"

Include Negative Instructions

Good: "Do not populate if care instructions are not visible in images"
Bad: "Include care instructions"

Complete Schema Example

Here’s how a well-configured schema might look:

Block	Field Type	Key Rules	Assets
title	string	5-10 words, include product name	Tone of Voice
description	string	Max 150 words, 2 paragraphs	Tone of Voice, Stop Words, Seasonal Trends
attributes	array[object]	Only relevant, accurate attributes	Attributes List
taxonomy	array[string]	Match to category hierarchy	Taxonomy JSON
key_features_and_benefits	array[string]	5 bullet points	Tone of Voice, Seasonal Trends
styling_advice	array[string]	3-5 styling options	Tone of Voice, Seasonal Trends
care_instructions	array[object]	Only if visible in images	None
meta_title	string	”Buy [Title] from [Brand]” format	None
meta_description	string	120-155 characters	None
image_meta_data	array[object]	SEO image names and alt text	None
faqs	array[string]	2-3 common Q&As	None

Best Practices

Keep Rules Clear and Actionable

Write rules as if explaining to a human writer what you need. Be specific about:

• Word/character counts
• Format requirements
• What to include and exclude
• When to use passthrough vs. generate

Test Your Schema

After making changes, process a few test products to verify output:

1. Check that all fields generate correctly
2. Verify field types match expected format
3. Review content quality against your rules
4. Confirm asset guidance is being followed

Iterate and Improve

Review generated content and refine your rules based on results. Common adjustments include:

• Adding more specific constraints
• Including additional negative instructions
• Attaching more assets for guidance
• Adjusting passthrough configurations

Use Consistent Naming

Field names should be:

• Lowercase with underscores (e.g., key_features)
• Descriptive but concise
• Consistent across your schema

Troubleshooting

Content Not Generating Correctly?

• Check your rules for clarity and specificity
• Verify attached assets contain expected content
• Ensure field type matches your expected output format

Missing Information?

• Add more specific rules about what to include
• Check that relevant assets are attached
• Verify input data contains the expected information

Wrong Format?

• Review the Field Type setting
• For arrays, specify what each item should contain
• For objects, describe the expected structure

Content Too Generic?

• Attach more specific assets (tone of voice, seasonal trends)
• Add negative instructions (what NOT to write)
• Include examples of desired output in your rules