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"
}

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

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