# Concepts

OrbCatalog's seven nouns, from Type to Channel, and the shape of a stored Product.

The product database of the Orb family. Editors design Types and keep products in a fast panel; storefronts and OrbPage read published base data and short-lived offers through a CDN with the client; OrbCart and OrbSearch read it through the contracts they already have. One Postgres, one API, a CDN in front.

**The shape in one line:** a Product, with its Variants, is one typed document. A versioned **Schema** (the Types and the attributes they share) compiles at runtime into the validators, the panel's columns, the database's filter indexes, the OpenAPI description and the delivery projection. Drafts, versions, the publish audit and the change feed all work on that document. Offers live beside it, because a price is not content: their prices are a ledger that an ERP and the panel write side by side. Everything that changes with time is stored with its time and judged by the read, so nothing has to run at 09:00 for 09:00 to be right.

| Noun         | What it is                                                                                                                                                                                                                                                                                                       | Stored as                                                                          |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **Type**     | What a kind of product looks like: which attributes it uses, which are required, which are variant axes. Types are published together as one **Schema** version, so attributes like `brand` mean the same thing in every Type.                                                                                   | `schema_versions` (one immutable document per version)                             |
| **Product**  | One sellable thing, described once in every locale: the merchant's id (`ref`), name, slug, attributes, media, categories and its Variants.                                                                                                                                                                       | `products.draft` and `products.published` (`jsonb`), history as reverse patches    |
| **Variant**  | A concrete SKU inside the Product document, chosen by the Type's axes (size, colour).                                                                                                                                                                                                                            | nested in the Product document; `skus` holds the uniqueness index                  |
| **Category** | A node of the tree, with its own document (title, slug, description, pinned products).                                                                                                                                                                                                                           | `categories` (same draft and version machinery)                                    |
| **Register** | A list the Schema names, such as Brands, Series or Certifications, whose **Entries** are published documents of one fixed shape (name, slug, description, image, link). The Schema declares that a register exists and which attribute links to it; an editor or a Source adds entries without a Schema publish. | the Schema declares it; `entries` (same draft and version machinery as a category) |
| **Offer**    | What one SKU costs and whether it ships, in one Channel: its terms (availability, delivery days) and its prices, a ledger of base and sale entries from several writers. Never drafted, never versioned.                                                                                                         | `offers` (terms) and `offer_prices` (the append-only ledger)                       |
| **Channel**  | Where you sell: currency, locales, gross or net prices, country, and the shop's address in each locale. The family word, as in OrbCart and OrbSearch.                                                                                                                                                            | `orbcatalog.config.ts`                                                             |

A stored Product document. Attribute values are keyed by the attribute's stable id, localized values by locale; every public API shows the attribute's `key` instead:

```jsonc
{
  "name": { "de": "Alpin 30", "en": "Alpine 30" },
  "slug": { "de": "alpin-30", "en": "alpine-30" },
  "search": { "title": { "de": "Alpin 30 Wanderrucksack" } }, // the search listing; absent, the name is the title
  "attributes": {
    "atr_k2m9x0q1v7ce": ["deuter"], // brand (link to an entry of Brands)
    "atr_0p3w8n5t2r1a": 30, // volume (number, unit l)
    "atr_h6d1s9b4m2zz": {
      "de": { "type": "doc", "content": [] },
      "en": { "type": "doc", "content": [] },
    }, // description (rich text, localized)
  },
  "variants": [
    {
      "id": "var_4n8c2m6q0x1s",
      "sku": "BP-ALPIN-30-GRN",
      "axes": { "atr_c0l0urq8w2e4": "green" },
      "attributes": { "atr_gt1n0000ab12": "4012345678901" },
      "shipping": { "weightInGrams": 1150 },
      "taxCategory": "standard",
    },
  ],
  "media": [
    {
      "media": "med_1a2b3c4d5e6f",
      "width": 2000,
      "height": 2000,
      "alt": { "de": "Rucksack in Grün" },
    },
  ],
  "categories": ["outdoor/rucksaecke"],
}
```

A version spans **all locales**: shared facts (variants, SKUs, weights, media, categories) exist once, and each version names the locales it **releases**. German can go live today and English next week without a second copy of the product.

A brand is an entry, not an option of a choice: a new brand is data, never a type change, and it carries a logo, a text and its own site. The product links it by its ref, and every answer that shows the product shows the brand by name, slug and logo:

```jsonc
// GET /v1/registers/brands/entries/deuter?locale=de
{
  "object": "entry",
  "register": "brands",
  "ref": "deuter",
  "locale": "de",
  "name": "Deuter",
  "slug": "deuter",
  "urls": { "de": "https://nordgrat.de/brands/deuter" },
  "description": { "html": "<p>Rucksäcke aus Gersthofen, seit 1898.</p>" },
  "image": { "url": "https://media.nordgrat.de/med_7c1d9e3f5a2b/640", "width": 640, "height": 480 },
  "link": "https://www.deuter.com",
  "version": 3,
  "publishedAt": "2026-10-01T07:00:00.000Z",
  "sequence": 2107,
}
// and inside the product: "brand": [{ "ref": "deuter", "name": "Deuter", "slug": "deuter", "image": { … } }]
```

Where to go from here: [keep products in the admin](/docs/admin/catalog), [read them in a shop](/docs/shop/catalog), [sync them from a PIM or ERP](/docs/integrate/catalog-sources), [follow their changes](/docs/integrate/catalog-changes) and [every public read](/docs/catalog/http-api).