Most ecommerce operations start with a spreadsheet or a platform’s built-in product form and never formally decide on an attribute model. Fields get added ad hoc: someone needs a “care instructions” field, so it goes in as a custom field in BigCommerce. Someone needs a “country of origin” field for Amazon, so it goes in too. After two years, you have a product model with 80 fields, no documentation, inconsistent values, and nobody who knows what half of them are for.

This is the catalog debt problem. Here’s how to avoid it.

Start with Families, Not Fields

The most common mistake is modeling products as a flat list of attributes. In reality, different product types need different attributes. An apparel product needs material, size range, and care instructions. A book needs ISBN, author, and page count. A piece of software needs license type and supported platforms.

The right model groups attributes into families: a shared schema for a product type. Every product in the “Apparel” family has the same set of attributes. Every product in the “Electronics” family has a different set.

This has a few properties:

  • You can generate a Zod schema from a family, which means you can validate any product in that family against the same type.
  • Adding an attribute to a family makes it available to every product in that family — without a migration or a schema change.
  • You can tell at a glance what a product is supposed to have, and what it’s missing.

Type Your Attributes

Free-text fields are a catalog liability. An untyped “weight” field will contain “2 kg”, “2kg”, “2.0”, “approx. 2”, and “unknown” — and none of these parse the same way in a connector.

Attribute types in minipim:

  • text — localized, for human-readable strings
  • measurement — a numeric value plus a unit; validates both parts
  • money — amount plus currency, market-scoped
  • select — an enum; only allows predefined values
  • richtext — formatted content, localized
  • media — references to asset records

Type enforcement is the difference between data that can be reliably synced to channels and data that requires manual cleanup before every export.

Use Channel Scoping

Not every attribute is relevant to every channel. Amazon requires A+ content; your storefront doesn’t use it. A wholesale portal needs a trade price; Amazon shouldn’t see it.

Channel scoping lets you declare which channels an attribute is relevant to. The data is stored once but each channel only sees what it’s supposed to see. This keeps product records clean and prevents accidentally syncing fields to channels that don’t need them.

The Problem with Custom Fields Everywhere

Most commerce platforms offer “custom fields” or “metafields” as an escape valve. They’re useful, but they’re untyped, undocumented, and invisible to channel readiness scoring.

When you model an attribute as a proper typed field in the PIM schema, the PIM knows it exists, can validate it, can compute readiness based on whether it’s populated, and can map it to the correct field in each connector. When you put it in a custom field, none of that works — you’ve moved the problem into a less visible layer.

Naming Conventions and Documentation

Attribute keys should be machine-readable and consistent. net_weight not weight (net). care_guide_en not Care Guide. Lower-snake-case across the board.

Document every attribute in the family definition: what it’s for, what format it expects, which channels use it, and what the valid values are for select fields. This documentation doesn’t need to live in a separate wiki — the attribute definition in the PIM should carry it.

When to Refactor Your Attribute Model

You know your attribute model is broken when:

  • Connectors require custom transforms to handle inconsistent data formats
  • You’re adding the same attribute to products manually because it’s missing from the schema
  • A new channel requires attributes that don’t exist in your model and you’re not sure where to add them
  • You’ve hired a new merchandiser and they can’t figure out what fields are supposed to contain

The good news: refactoring attribute models in a schema-first PIM is a configuration change, not a database migration. You update the family definition, and the new attributes become available on every product in that family immediately.