> ## Documentation Index
> Fetch the complete documentation index at: https://docs.merchantops.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Product types & properties

> Templates and the attribute schema that define what your products can hold.

Two entities define the shape of your catalog: **property definitions** describe
individual attributes, and **product types** group them into templates that
products validate against. This page explains both and the order in which you
create them. For the shared vocabulary, see [Core concepts](/getting-started/concepts).

## Property definitions

A property definition is the schema for a single attribute — what it's called,
what kind of value it holds, and how it behaves. Every attribute on a product or
variant traces back to one.

<ResponseField name="key & name" type="identity">
  A machine-readable `key` (unique within your organization) and a human-readable
  name. Keys start with a letter and use letters, numbers, underscores, hyphens,
  or spaces.
</ResponseField>

<ResponseField name="type" type="value kind">
  The kind of value the property holds — including text, rich text, number,
  boolean, enum (a fixed set of allowed values), date, URL, and string list.
  The type governs how the value is entered, validated, and displayed.
</ResponseField>

<ResponseField name="level" type="product or variant">
  Whether the property lives at the **product** level (shared across all the
  product's variants, e.g. description) or the **variant** level (differs per
  buyable version, e.g. size or color).
</ResponseField>

<ResponseField name="required / searchable / facetable" type="behavior flags">
  Whether a value must be present, whether it participates in search, and whether
  it can be used as a storefront filter (facet).
</ResponseField>

<ResponseField name="category" type="grouping">
  An optional grouping label. For how properties are arranged into sections on the
  product page, see [Display groups & labels](/catalog/display-groups-labels).
</ResponseField>

## Product types

A product type is a template — a named set of property definitions that a class of
products shares. "Running Shoe" and "Jacket" are product types; each links the
property definitions its products should carry. A product references exactly one
product type, and its attributes are validated against that type.

<Note>
  A product type **links** property definitions rather than redefining them, so the
  same definition (say, `color`) can be reused across many types. A type may also
  override display placement for a property without changing the underlying
  definition.
</Note>

## Create them in order

Because each entity references the one before it, set them up in dependency
order:

<Steps>
  <Step title="Property definitions">
    Define the attributes first — a product type can only link definitions that
    already exist.
  </Step>

  <Step title="Product types">
    Create the templates that link those property definitions.
  </Step>

  <Step title="Products">
    Create products against a product type. A product can only reference a type
    that already exists.
  </Step>
</Steps>

<Warning>
  Creating these out of order causes validation errors. If a product fails to
  validate, confirm its product type exists and that every property it references
  has a definition.
</Warning>

## Attribute standardization

Merchants and brands describe the same attribute in many ways — "blk", "Black",
and "true black" all mean one color. When [enrichment](/getting-started/concepts)
fills in an attribute, it standardizes the value to your catalog's canonical form
so products stay consistent and filterable.

You control how strict this is per property definition:

* **Exact-match-only** — for properties where a near miss is unacceptable
  (typically numeric or size-critical attributes), matching must be exact rather
  than approximate.
* **Allow new values** — when enabled, enrichment may create a new standardized
  value if none of the existing ones fit; when disabled, it only ever picks from
  values already in your catalog.
* **Matching guidance** — free-text instructions that steer how a specific
  property is matched.

<Note>
  Standardization is applied at the property level as part of enrichment. It reuses
  your existing values wherever possible so the same concept isn't recorded two
  ways.
</Note>

<CardGroup cols={2}>
  <Card title="Products & variants" icon="box" href="/catalog/products-variants">
    What products and variants hold and how they relate.
  </Card>

  <Card title="Display groups & labels" icon="layer-group" href="/catalog/display-groups-labels">
    Organize properties into sections and tag product versions.
  </Card>
</CardGroup>