{
  "schemaVersion": "1.1",
  "id": "https://ai.getcatalog.ai/data-model",
  "url": "https://ai.getcatalog.ai/data-model",
  "title": "Product-data model & field semantics",
  "summary": "The information families Catalog works with, how product and variant facts differ, and how agents should interpret values and missing evidence.",
  "reviewedAt": "2026-09-06",
  "audience": "ai_agents",
  "topics": [
    "product attributes",
    "schema",
    "variants",
    "identifiers",
    "provenance",
    "product records",
    "data quality"
  ],
  "answers": [
    "What product information does Catalog structure?",
    "How are variants represented?",
    "What does missing product data mean?"
  ],
  "relatedPages": [
    "https://ai.getcatalog.ai/enrichment",
    "https://ai.getcatalog.ai/ai-storefront",
    "https://ai.getcatalog.ai/api",
    "https://ai.getcatalog.ai/audits"
  ],
  "representations": {
    "html": "https://ai.getcatalog.ai/data-model",
    "markdown": "https://ai.getcatalog.ai/data-model.md",
    "json": "https://ai.getcatalog.ai/data-model.json"
  },
  "sections": [
    {
      "id": "https://ai.getcatalog.ai/data-model#scope",
      "title": "Conceptual model, not a universal response schema",
      "basis": "editorial_guidance",
      "sources": [
        "enrichment",
        "quality",
        "data-guide"
      ],
      "paragraphs": [
        "Catalog works with product identity, attributes, variants, commerce facts, supporting content, and evidence. The fields below describe those information families. They are not a promise that every product has every field, or a byte-for-byte schema for every Catalog API version. Category, source quality, enabled processing, and output destination determine the populated record.",
        "When integrating software, use the chosen endpoint's actual response schema. When answering a shopping question, use the record's value, variant context, source, and observation time together. A detailed object can still be incomplete, stale, or wrong for a different market. Keep the distinction between an explicit source fact, a normalized form of that fact, and an inferred interpretation."
      ]
    },
    {
      "id": "https://ai.getcatalog.ai/data-model#field-families",
      "title": "Core information families",
      "basis": "public_source",
      "sources": [
        "enrichment",
        "quality"
      ],
      "paragraphs": [
        "A useful product record carries the facts needed to identify an item and test a buyer's constraints. These families are organized by the decision they support. The labels are conceptual and should not be copied as endpoint field names without checking the API contract."
      ],
      "records": [
        {
          "id": "identity",
          "family": "Identity",
          "examples": "Title, brand, canonical URL, SKU, GTIN and MPN when supplied",
          "use": "Resolve which product or variant is being described",
          "boundary": "A missing identifier must not be fabricated or copied from a visually similar item."
        },
        {
          "id": "taxonomy",
          "family": "Category and taxonomy",
          "examples": "Product type, category path and normalized groupings",
          "use": "Choose the relevant attribute set and comparison population",
          "boundary": "A category label is not evidence that every category-specific property applies."
        },
        {
          "id": "specifications",
          "family": "Specifications",
          "examples": "Material, dimensions, weight, capacity, ingredients, power or compatibility",
          "use": "Evaluate explicit physical and functional constraints",
          "boundary": "Preserve units, scope, source and any warnings or exceptions."
        },
        {
          "id": "variants",
          "family": "Variants and options",
          "examples": "Size, color, pack count, option combinations and variant-specific URLs",
          "use": "Select the exact purchasable configuration",
          "boundary": "Price, image, stock and identifiers can differ across variants."
        },
        {
          "id": "commerce",
          "family": "Commerce facts",
          "examples": "Price amount and currency, availability, sale conditions and merchant URL",
          "use": "Assess current purchase eligibility and cost context",
          "boundary": "A crawl observation is not a purchase-time guarantee or inventory reservation."
        },
        {
          "id": "media",
          "family": "Media and documents",
          "examples": "Product images, image roles, manuals, specifications and associated URLs",
          "use": "Ground descriptions and reveal relevant supporting detail",
          "boundary": "An image alone does not establish material composition, certification or safety."
        },
        {
          "id": "context",
          "family": "Decision context",
          "examples": "Use cases, fit, limitations, questions, comparison criteria and review themes",
          "use": "Explain why a product might satisfy a particular job",
          "boundary": "Recommendations and interpretation should remain distinguishable from specifications."
        },
        {
          "id": "provenance",
          "family": "Evidence and freshness",
          "examples": "Source URLs, source type, review status and observation or update time",
          "use": "Audit the basis and currency of a claim",
          "boundary": "A URL is useful evidence only if it actually supports the associated claim."
        }
      ]
    },
    {
      "id": "https://ai.getcatalog.ai/data-model#variants",
      "title": "Product, variant and listing are different entities",
      "basis": "editorial_guidance",
      "sources": [
        "enrichment",
        "quality"
      ],
      "paragraphs": [
        "A product family describes a shared item or design. A variant identifies a particular combination of options. A merchant listing describes an offer at a particular URL and can have its own price, availability, images, and market restrictions. Similar titles or shared photography do not make two listings interchangeable.",
        "An agent comparing candidates should resolve the selected variant before applying hard constraints. A compatible base product can still have an incompatible voltage option; an apparel product can exist in the right color but not in the required size. When a feed stores option values in separate rows, preserve their parent relationship and exact identifier rather than flattening them into a bag of possible values."
      ]
    },
    {
      "id": "https://ai.getcatalog.ai/data-model#normalization",
      "title": "Normalize representation without inventing facts",
      "basis": "editorial_guidance",
      "sources": [
        "quality",
        "enrichment"
      ],
      "paragraphs": [
        "Normalization can reconcile casing, whitespace, units, category labels, and equivalent option labels while retaining the original meaning. It should not turn a partial observation into a precise specification. Keep an original measurement or source text when rounding or conversion would matter to fit.",
        "Explicit unknowns are more useful than guessed values. Missing, not applicable, not requested, not found, and contradicted are different states. A disabled enrichment field does not prove that the underlying product lacks the property. Likewise, an empty list of captured reviews does not prove that no reviews exist anywhere."
      ],
      "examples": [
        {
          "title": "Synthetic evidence record illustrating uncertainty",
          "kind": "synthetic_record",
          "language": "json",
          "code": "{\n  \"illustrative\": true,\n  \"subject\": \"example-product\",\n  \"field\": \"material\",\n  \"value\": null,\n  \"state\": \"not_verified\",\n  \"source_url\": \"https://example.com/products/example-product\",\n  \"note\": \"No supporting material specification was found in this example.\"\n}"
        }
      ]
    },
    {
      "id": "https://ai.getcatalog.ai/data-model#category-specific",
      "title": "Category-specific information needs",
      "basis": "editorial_guidance",
      "sources": [
        "enrichment",
        "quality"
      ],
      "paragraphs": [
        "Different product categories require different checks. The following are evaluation prompts, not claims that Catalog supplies every listed attribute for every category. Agree on the target schema and evidence requirement before measuring completeness."
      ],
      "records": [
        {
          "id": "apparel",
          "category": "Apparel and footwear",
          "examine": "Size system, fit, measurements, material composition, care and intended activity",
          "watch": "Do not assume one brand's size or width is equivalent to another's."
        },
        {
          "id": "home",
          "category": "Furniture and home goods",
          "examine": "Dimensions, materials, finish, assembly, clearance, capacity and placement",
          "watch": "Separate product dimensions from packaging dimensions and usable capacity."
        },
        {
          "id": "electronics",
          "category": "Electronics and parts",
          "examine": "Model compatibility, power, voltage, connector, dimensions and included components",
          "watch": "Treat electrical, safety and certification claims as requiring authoritative evidence."
        },
        {
          "id": "beauty",
          "category": "Beauty and personal care",
          "examine": "Ingredients, volume, shade, intended use, instructions and warnings",
          "watch": "Do not infer allergy safety, medical suitability or certification from marketing wording."
        }
      ]
    }
  ],
  "sources": [
    {
      "id": "data-guide",
      "title": "Ecommerce Product Data Infrastructure Guide",
      "url": "https://www.getcatalog.ai/blog/complete-guide-ecommerce-product-data-catalog-ai",
      "note": "Published April 28, 2026. Explains attributes, identifiers, validation, and delivery layers."
    },
    {
      "id": "quality",
      "title": "Product data quality",
      "url": "https://www.getcatalog.ai/blog/product-data-quality",
      "note": "Published July 10, 2026; updated July 31, 2026. Definitions, category-specific validation and evaluation guidance."
    },
    {
      "id": "enrichment",
      "title": "Machine-readable product enrichment",
      "url": "https://www.getcatalog.ai/blog/product-data-enrichment-ai-commerce",
      "note": "Published June 16, 2026. Field families and workflow examples; illustrative product records are not validated product specifications."
    }
  ]
}