# Data Model

The Apiera PIM data model is organized around **products** as the central entity, with supporting resources for
taxonomy, content, assets, and distribution.

## Core entities

### Product

The central entity. A product represents a single item in your catalog.

| Field | Description |
|  --- | --- |
| `type` | `simple`, `parent` (variant parent), or `variant`. |
| `familyUuid` | Optional. Links to a product family that defines its data structure. |
| `parentUuid` | For variants only. Links to the parent product. |
| `brandUuid` | Optional. Links to a brand. |


Products connect to most other entities in the system through sub-resources:

- **ProductAttribute** - Links a product to an attribute (e.g. "Color").
- **ProductAttributeTerm** - Links a product attribute to a specific term (e.g. "Red").
- **ProductCategory** - Links a product to a category.
- **ProductTag** - Links a product to a tag.
- **ProductAsset** - Links a product to an asset (image, document, etc.) with a type and sort order.
- **ProductRelation** - Links a product to another product with a relation type (e.g. "accessory", "spare part").
- **ProductInputValue** - Stores a product's field values, scoped by channel and locale.


### Product family

A template that defines the data structure for a group of products. Families specify which attributes, categories,
asset types, input types, and relation types are relevant for their products, along with requirement levels.

| Sub-resource | Purpose |
|  --- | --- |
| FamilyAttribute | Which attributes apply, with requirement level (`must`, `should`, `may`, `mustNot`). |
| FamilyCategory | Which categories apply, with requirement level. |
| FamilyAssetType | Which asset types apply, with min/max counts and product type applicability. |
| FamilyInputType | Which input types apply, with requirement level and product type applicability. |
| FamilyRelationType | Which relation types apply, with min/max counts. |


Families support **hierarchy** through a `parentUuid` field, allowing child families to inherit configuration from
their parent.

### Taxonomy

Taxonomy resources organize and classify products:

- **Attribute** - A product property (e.g. "Color", "Material"). Contains attribute terms.
- **AttributeTerm** - A specific value for an attribute (e.g. "Red", "Cotton").
- **Category** - A hierarchical classification (supports parent/child via `parentUuid`).
- **Tag** - A flat label for flexible grouping.
- **Brand** - A product brand.
- **ProductAssetType** - Defines types of assets (e.g. "Main Image", "Datasheet"). Has an `isFeatured` flag.
- **ProductRelationType** - Defines types of product relations with direction and optional reverse relation.


### Asset

An asset represents a file (image, document, video, etc.) in the system:

- **Asset** - The container with metadata, category, and storage location.
- **File** - An individual file version within an asset, with MIME type, checksum, and storage key.
- **AssetMetadata** - Key-value pairs for additional metadata (dimensions, EXIF data, etc.).
- **Collection** - A hierarchical folder structure for organizing assets.


### Input type

Input types define the data fields available for product content:

- **TypeGroup** - Groups related input types together. Scoped by entity type.
- **InputType** - A specific field definition with data type, validation rules (min/max length, pattern), and flags
for localizability and uniqueness.


### Channel

A channel represents a distribution target (e.g. "Web Store", "Print Catalog"):

- **Channel** - The distribution target with a code and display name.
- **ChannelInputType** - Defines which input types are available in a channel, with requirement level and whether
the value is scopable.


### Locale

A locale defines a language/region for localized content, using BCP 47 codes (e.g. `en-US`, `nb-NO`). One locale per
organization is marked as the default.

## How entities connect

The product sits at the center of the data model, connecting to taxonomy, content, and distribution:


```
                        Product Family
                        (template)
                             |
                             | familyUuid
                             v
Brand  ---brandUuid--->  Product  <---parentUuid--- Product (variant)
                          |   |
            +-------------+   +-------------+
            |             |                 |
            v             v                 v
     ProductAttribute  ProductAsset   ProductInputValue
            |              |               |    |
            v              v               v    v
       Attribute        Asset          Channel  Locale
            |
            v
      AttributeTerm
```

**Key patterns:**

- **Products reference taxonomy by UUID.** A `ProductAttribute` stores the product UUID and the attribute UUID.
The attribute itself is managed in the taxonomy service.
- **Input values are scoped.** Each `ProductInputValue` can be scoped to a specific channel and locale, enabling
per-market, per-language content.
- **Families define structure, products hold data.** The family says "products in this group should have a Color
attribute". The product actually links to the Color attribute and its terms.
- **Assets are shared.** An asset exists independently and can be linked to multiple products via `ProductAsset`.


## Identifiers

All entities use UUID v7 as their primary identifier. UUIDs are generated server-side and returned in creation
responses. You cannot specify your own UUIDs.

## Timestamps

All entities include `createdAt` and `updatedAt` timestamps in UTC. Entities that support soft deletion also include
`removedAt`. Products additionally include `archivedAt`.