Product Specification

Define product data for optimal agent discovery and negotiation.

Overview

The Hyperfold product schema is designed for AI agent consumption—rich semantic data, explicit pricing rules, and machine-readable attributes. While traditional e-commerce focuses on human-readable descriptions, our schema emphasizes structured data that agents can reason about.

Products can be imported from Shopify, CSV, or JSON. Hyperfold automatically enriches basic product data with semantic fields during import.

Product Schema

The complete product schema with all available fields:

json

{
  "product_id": "prod_aero_x2",
  "sku": "AERO-X2-BLU-10",
  "name": "AeroRun X2 Marathon Shoe",
  "description": "Professional marathon running shoe with Gore-Tex waterproofing...",
 
  "pricing": {
    "list_price": 180.00,
    "currency": "USD",
    "cost": 72.00,
    "min_margin": 0.15,
    "negotiable": true,
    "msrp": 199.00
  },
 
  "inventory": {
    "quantity": 847,
    "warehouse": "us-west-1",
    "reorder_point": 100,
    "status": "in_stock"
  },
 
  "semantics": {
    "category": "apparel/footwear/running",
    "usage_context": ["marathon", "trail", "wet_conditions"],
    "visual_tags": ["blue", "reflective", "mesh_upper"],
    "vibe_tags": ["professional", "performance", "outdoor"],
    "target_audience": ["serious_runner", "athlete"]
  },
 
  "attributes": {
    "brand": "AeroRun",
    "weight_g": 280,
    "heel_drop_mm": 8,
    "waterproof": true,
    "breathable": true,
    "material": "Gore-Tex, mesh, EVA foam"
  },
 
  "media": {
    "images": [
      {"url": "https://cdn.example.com/aero-x2-main.jpg", "alt": "AeroRun X2 side view"},
      {"url": "https://cdn.example.com/aero-x2-top.jpg", "alt": "AeroRun X2 top view"}
    ],
    "video_url": "https://cdn.example.com/aero-x2-demo.mp4"
  },
 
  "variants": [
    {"sku": "AERO-X2-BLU-9", "size": "9", "color": "blue", "quantity": 120},
    {"sku": "AERO-X2-BLU-10", "size": "10", "color": "blue", "quantity": 89},
    {"sku": "AERO-X2-BLK-10", "size": "10", "color": "black", "quantity": 156}
  ],
 
  "metadata": {
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-12-19T08:30:00Z",
    "source": "shopify_import",
    "tags": ["featured", "new_arrival", "best_seller"]
  }
}

Required Fields

At minimum, products need these fields for basic functionality:

json

{
  "product_id": "prod_basic_tee",
  "name": "Basic Cotton T-Shirt",
  "description": "Comfortable cotton t-shirt for everyday wear",
  "pricing": {
    "list_price": 29.99,
    "currency": "USD"
  },
  "inventory": {
    "quantity": 500,
    "status": "in_stock"
  }
}

Field	Type	Description
`product_id`	string	Unique identifier (auto-generated if not provided)
`name`	string	Product name (max 200 characters)
`description`	string	Product description (max 5000 characters)
`pricing.list_price`	number	Base price in specified currency
`pricing.currency`	string	ISO 4217 currency code
`inventory.quantity`	number	Available stock count

Semantic Fields

Semantic fields enable intelligent product discovery. While optional, they significantly improve agent matching accuracy:

json

"semantics": {
  // Hierarchical category for filtering
  "category": "apparel/footwear/running",
 
  // When/where the product is used
  "usage_context": [
    "marathon",        // Event type
    "trail",           // Terrain
    "wet_conditions"   // Weather
  ],
 
  // Visual characteristics (from image analysis)
  "visual_tags": [
    "blue",            // Primary color
    "reflective",      // Safety features
    "mesh_upper",      // Material appearance
    "chunky_sole"      // Style
  ],
 
  // Lifestyle/aesthetic tags
  "vibe_tags": [
    "professional",    // User level
    "performance",     // Focus
    "outdoor",         // Environment
    "serious_runner"   // Identity
  ],
 
  // Target customer segments
  "target_audience": [
    "athlete",
    "fitness_enthusiast",
    "outdoor_adventurer"
  ]
}

If semantic fields are not provided, Hyperfold auto-generates them using thecatalog optimize command. Auto-generated fields may be less accurate than hand-curated ones.

Pricing Configuration

Pricing fields control how agents negotiate:

json

"pricing": {
  // Customer-facing price
  "list_price": 180.00,
  "currency": "USD",
 
  // Your cost (for margin calculation)
  "cost": 72.00,
 
  // Minimum acceptable margin (floor = cost * (1 + min_margin))
  // Floor price = $72 * 1.15 = $82.80
  "min_margin": 0.15,
 
  // Can agents negotiate this price?
  "negotiable": true,
 
  // Manufacturer suggested retail (for reference)
  "msrp": 199.00,
 
  // Optional: tier-specific pricing
  "tier_pricing": {
    "gold": 162.00,    // 10% off for gold members
    "silver": 171.00,  // 5% off for silver members
    "wholesale": 126.00 // 30% off for wholesale
  }
}

Floor Price Calculation

The floor price is the absolute minimum an agent will accept:

floor_price = cost × (1 + min_margin)
floor_price = $72.00 × 1.15 = $82.80

Product Variants

Products with multiple options (size, color) use variants:

Field	Description
`variants[].sku`	Unique SKU for this variant
`variants[].size`	Size value (string)
`variants[].color`	Color value (string)
`variants[].quantity`	Stock for this variant
`variants[].price_adjustment`	Optional price modifier (+/- from base)

Validating Products

bash

# Validate a product file against the schema
$ hyperfold catalog validate ./products/shoe.json
 
> [Schema] Validating against product schema v2.1...
> [Required] Checking required fields...
> [Pricing] Validating pricing configuration...
> [Semantics] Checking semantic field formats...
 
✓ Validation passed
 
PRODUCT SUMMARY
  ID:           prod_aero_x2
  Name:         AeroRun X2 Marathon Shoe
  List Price:   $180.00
  Floor Price:  $82.80 (15% min margin)
  Variants:     3
 
SEMANTIC COVERAGE
  Category:     ✓ apparel/footwear/running
  Usage:        ✓ 3 contexts defined
  Visual:       ✓ 4 tags (auto-enrichable)
  Vibe:         ✓ 4 tags defined

Ready to import products? See Product Import.