Schéma du catalogue

Quand tu upload un catalogue via l’API Dialog, le JSON doit respecter ce schéma. L’assistant IA Dialog utilise ces données structurées pour comprendre tes produits et recommander juste.

À quoi Dialog utilise le catalogue

• Comprendre les features, variantes et specs des produits.
• Faire des comparaisons produit intelligentes.
• Fournir des recommandations contextuelles selon les besoins du client.
• Répondre aux questions détaillées sur ton inventaire.

Plus ton catalogue est complet et structuré, meilleures sont les réponses.

JSON Schema

Colle-le dans ton validateur (Ajv, jsonschema, Pydantic via model_json_schema, etc.) pour valider tes payloads avant l’upload.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Dialog product catalog",
  "type": "object",
  "required": ["products"],
  "properties": {
    "products": {
      "type": "array",
      "items": { "$ref": "#/definitions/product" }
    }
  },
  "definitions": {
    "product": {
      "type": "object",
      "required": ["id", "title", "status", "variants", "metafields", "collections", "tags"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Identifiant unique du produit dans ton système. Doit être stable entre imports."
        },
        "title": { "type": "string" },
        "status": { "$ref": "#/definitions/status" },
        "variants": {
          "type": "array",
          "minItems": 1,
          "items": { "$ref": "#/definitions/productVariant" }
        },
        "metafields": {
          "type": "array",
          "items": { "$ref": "#/definitions/metafield" }
        },
        "collections": {
          "type": "array",
          "items": { "$ref": "#/definitions/collection" }
        },
        "tags": {
          "type": "array",
          "items": { "type": "string" }
        },
        "description": { "type": "string" },
        "translations": { "$ref": "#/definitions/productTranslations" },
        "featuredImage": { "$ref": "#/definitions/image" },
        "images": {
          "type": "array",
          "items": { "$ref": "#/definitions/image" }
        },
        "options": {
          "type": "array",
          "items": { "$ref": "#/definitions/option" }
        }
      }
    },
    "productVariant": {
      "type": "object",
      "required": ["id", "displayName", "inStock", "price"],
      "properties": {
        "id": { "type": "string" },
        "displayName": { "type": "string" },
        "inStock": { "type": "boolean" },
        "price": {
          "type": "array",
          "minItems": 1,
          "items": { "$ref": "#/definitions/price" },
          "description": "Une entrée par devise supportée."
        },
        "translations": { "$ref": "#/definitions/variantTranslations" },
        "selectedOptions": {
          "type": "array",
          "items": { "$ref": "#/definitions/selectedOption" }
        },
        "metafields": {
          "type": "array",
          "items": { "$ref": "#/definitions/metafield" }
        },
        "compareAtPrice": {
          "type": "array",
          "items": { "$ref": "#/definitions/price" },
          "description": "Prix d'origine, pour afficher la remise."
        },
        "image": { "$ref": "#/definitions/image" }
      }
    },
    "image": {
      "type": "object",
      "required": ["url"],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "URL directe — HTTPS fortement recommandé."
        }
      }
    },
    "price": {
      "type": "object",
      "required": ["amount", "currencyCode"],
      "properties": {
        "amount": {
          "type": "string",
          "pattern": "^\\d+(\\.\\d+)?$",
          "description": "Décimal encodé en string, ex. \"29.99\". Pas un nombre."
        },
        "currencyCode": { "$ref": "#/definitions/currencyCode" }
      }
    },
    "metafield": {
      "type": "object",
      "required": ["name", "value"],
      "properties": {
        "name": {
          "type": "string",
          "description": "ex. \"material\", \"weight\", \"brand\"."
        },
        "value": {
          "type": "string",
          "description": "ex. \"cotton\", \"2.5kg\", \"Nike\"."
        }
      }
    },
    "collection": {
      "type": "object",
      "required": ["title"],
      "properties": {
        "title": { "type": "string" },
        "description": { "type": "string" }
      }
    },
    "option": {
      "type": "object",
      "required": ["id", "name", "values", "position"],
      "properties": {
        "id": { "type": "string" },
        "name": {
          "type": "string",
          "description": "ex. \"Color\", \"Size\", \"Material\"."
        },
        "values": {
          "type": "array",
          "items": { "type": "string" }
        },
        "position": {
          "type": "integer",
          "minimum": 0,
          "description": "Ordre d'affichage 0-based."
        },
        "translations": {
          "type": "array",
          "items": { "$ref": "#/definitions/optionTranslations" }
        }
      }
    },
    "selectedOption": {
      "type": "object",
      "required": ["name", "value"],
      "properties": {
        "name": { "type": "string" },
        "value": { "type": "string" },
        "translations": {
          "type": "object",
          "description": "Map locale → nom/valeur traduits.",
          "additionalProperties": {
            "type": "object",
            "required": ["name", "value"],
            "properties": {
              "name": { "type": "string" },
              "value": { "type": "string" }
            }
          }
        }
      }
    },
    "productTranslations": {
      "type": "object",
      "description": "Map locale (ISO en minuscules, ex. \"en\", \"fr\") → champs traduits.",
      "additionalProperties": {
        "type": "object",
        "required": ["title"],
        "properties": {
          "title": { "type": "string" }
        }
      }
    },
    "variantTranslations": {
      "type": "object",
      "description": "Map locale → champs traduits.",
      "additionalProperties": {
        "type": "object",
        "required": ["displayName"],
        "properties": {
          "displayName": { "type": "string" }
        }
      }
    },
    "optionTranslations": {
      "type": "object",
      "required": ["key", "value"],
      "properties": {
        "key": { "type": "string" },
        "value": { "type": "string" }
      }
    },
    "currencyCode": {
      "type": "string",
      "enum": ["EUR", "USD", "CAD", "GBP"]
    },
    "status": {
      "type": "string",
      "enum": ["ACTIVE", "ARCHIVED", "DRAFT"],
      "description": "ACTIVE : disponible à la vente. ARCHIVED : plus disponible, gardé pour référence. DRAFT : pas encore prêt à la vente."
    }
  }
}

Payload exemple

{
  "products": [
    {
      "id": "prod_001",
      "title": "T-shirt premium en coton",
      "description": "T-shirt confortable 100% coton bio, parfait pour tous les jours.",
      "status": "ACTIVE",
      "collections": [
        { "title": "Collection Été", "description": "Essentiels d'été légers et respirants" },
        { "title": "Eco-Friendly" }
      ],
      "tags": ["coton", "été", "casual", "bio"],
      "metafields": [
        { "name": "material", "value": "100% coton bio" },
        { "name": "care_instructions", "value": "Lavage à froid, séchage doux" }
      ],
      "featuredImage": { "url": "https://example.com/images/tshirt-main.jpg" },
      "images": [
        { "url": "https://example.com/images/tshirt-front.jpg" },
        { "url": "https://example.com/images/tshirt-back.jpg" }
      ],
      "options": [
        { "id": "color", "name": "Color", "values": ["Red", "Blue", "Green"], "position": 0 },
        { "id": "size", "name": "Size", "values": ["S", "M", "L", "XL"], "position": 1 }
      ],
      "variants": [
        {
          "id": "var_001",
          "displayName": "T-shirt rouge - Medium",
          "inStock": true,
          "price": [
            { "amount": "29.99", "currencyCode": "USD" },
            { "amount": "25.99", "currencyCode": "EUR" }
          ],
          "selectedOptions": [
            { "name": "Color", "value": "Red" },
            { "name": "Size", "value": "M" }
          ],
          "compareAtPrice": [{ "amount": "39.99", "currencyCode": "USD" }],
          "image": { "url": "https://example.com/images/tshirt-red-m.jpg" }
        }
      ]
    }
  ]
}

Tips de validation

• L’objet racine doit contenir products en array.
• Chaque produit doit avoir au moins une variante.
• price.amount est une string, pas un nombre.
• Utilise les codes ISO en minuscules pour les locales (en, fr, es).

Upload le fichier en utilisant l’URL pré-signée de la Référence API.