# Data Model & Asset Pack Structure

## Asset Pack Overview

A Ford BnP asset pack is a ZIP file containing:

1. **`linkingrecord.json`** — The manifest that describes every image, its category, viewing angle, associated features, and layering info
2. **Image files** — Organized in subdirectories by viewtype and imagetype

The `linkingrecord.json` is the single source of truth. Every QC check reads this file to understand what the pack should contain.

## linkingrecord.json Schema

```mermaid
graph TD
    ROOT[linkingrecord.json] --> MARKET[market: string]
    ROOT --> MODEL[model: string]
    ROOT --> YEAR[year: string]
    ROOT --> FULLLOAD[fullLoad: string]
    ROOT --> HEADER[header: object]
    ROOT --> ITEMS[items: array]

    HEADER --> SPECMARKET[specMarket: string]
    HEADER --> PTVL[ptvl: string]
    HEADER --> NUMMMY[numericalMmy: string]

    ITEMS --> ITEM1[Item]
    ITEM1 --> CONDITIONS[conditions: object]
    ITEM1 --> RECORDS[records: array]
    ITEM1 --> COUNT[count: integer]

    CONDITIONS --> VT[viewtype: string]
    CONDITIONS --> IT[imagetype: string]
    CONDITIONS --> EC[experienceCondition: string]
    CONDITIONS --> VAR[variant: string]

    RECORDS --> REC1[Record]
    REC1 --> ANGLE[angle: integer]
    REC1 --> FEATURES[features: array of strings]
    REC1 --> ASSETS[assets: array]

    ASSETS --> ASSET1[Asset]
    ASSET1 --> FILENAME[filename: string]
    ASSET1 --> LAYER[layer: integer]
```

### Top-Level Fields

| Field | Type | Example | Validation Rules |
|-------|------|---------|-----------------|
| `market` | string | `"DEU"` | Exactly 3 uppercase letters (A-Z) |
| `model` | string | `"CGW07"` | Uppercase letters and digits only |
| `year` | string | `"YYY"` | Must be the literal string `"YYY"` |
| `fullLoad` | string | `"Y"` | Load indicator |
| `header` | object | — | Contains metadata fields |
| `items` | array | — | Array of item objects |

### Header Fields

| Field | Type | Example | Validation Rules |
|-------|------|---------|-----------------|
| `specMarket` | string | `"WAEDX"` | Specification market code |
| `ptvl` | string | `"CGW"` | Platform code |
| `numericalMmy` | string | `"202400"` | Must contain no dots |

### Item Fields

Each item represents a group of images sharing the same viewtype/imagetype conditions.

| Field | Type | Example | Description |
|-------|------|---------|-------------|
| `conditions.viewtype` | string | `"exterior"` | View category (see matrix below) |
| `conditions.imagetype` | string | `"layeroptext"` | Image subcategory (see matrix below) |
| `conditions.experienceCondition` | string | `"2d-background"` | Optional. Presence indicates MEC pack |
| `conditions.variant` | string | `"desktop"` | Optional. Used for beltline images |
| `records` | array | — | Array of record objects |
| `count` | integer | `8` | Number of records in this item |

### Record Fields

Each record represents a specific configuration (angle + feature combination) with its image files.

| Field | Type | Example | Description |
|-------|------|---------|-------------|
| `angle` | integer | `21` | Camera viewing angle |
| `features` | array | `["bs-sa", "vs-kz", "pn4hq"]` | WERS feature/option codes |
| `assets` | array | — | Image files for this record |

### Asset Fields

| Field | Type | Example | Description |
|-------|------|---------|-------------|
| `filename` | string | `"ext/base/ext_21_bs-sa.jpg"` | File path relative to ZIP root |
| `layer` | integer | `0` | Layer stacking order (0 = base image) |

## ViewType / ImageType Matrix

| ViewType | ImageType | Description | Format | Resolution (BAU) |
|----------|-----------|-------------|--------|-----------------|
| `exterior` | *(none)* | Base exterior renders | JPEG (PNG accepted) | 1600x900 |
| `exterior` | `layeroptext` | Exterior layered options | PNG | 1600x900 |
| `exterior` | `showroom` | Showroom previews | PNG | 768x432 |
| `interior` | *(none)* | Base interior renders | JPEG (PNG accepted) | 1600x900 |
| `interior` | `layeroptint` | Interior layered options | PNG | 1600x900 |
| `carousel` | `colour` | Color chip thumbnails | JPEG | 148x83 |
| `carousel` | `powertrain` | Powertrain images | JPEG | 678x381 |
| `carousel` | `extra` | Extra option carousel images | JPEG | 678x381 |
| `carousel` | `bodystyle` | Body style images | JPEG | 678x381 |
| `carousel` | `series` | Series images | JPEG | 678x381 |
| `carousel` | `trim` | Trim images | JPEG | 678x381 |
| `lifestyle` | *(none)* | Lifestyle/marketing photo | JPEG | 1440x810 |
| `inventory` | *(none)* | Inventory/spec image | JPEG | 2900x1280 |
| `vehicleselector` | `desktop` | Beltline desktop frames | AVIF | 1920x842 |
| `vehicleselector` | `mobile` | Beltline mobile frames | AVIF | 640x428 |

> MEC packs use different resolutions for some types — see the [QC Checks Reference](04-qc-checks-reference.md#7-image-resolution-check).

## Pack Types: MEC vs BAU

Asset packs come in two variants with different validation rules:

### BAU (Business As Usual)
- Standard configurator packs
- No `experienceCondition` field present on any item
- Standard resolution and format requirements

### MEC (Multi-Experience Configurator)
- Enhanced packs with 2D background experience
- **Detection**: Any item with `conditions.experienceCondition = "2d-background"` makes the entire pack MEC
- Additional requirements:
  - Must have exterior 2d-background section with angle 30
  - Must have carousel/powertrain with assets
  - Required section pairs (regular + 2d-background) for exterior base, interior base, exterior layered options, interior layered options
  - Different resolution requirements (e.g., 1600x1600 instead of 1600x900 for base images)
  - Stricter format rules (base assets must be JPEG only, no PNG)
  - 100% WERS code coverage required for extra carousel (vs 50% minimum for BAU)

## Allowed File Types

Only these file extensions are permitted in asset packs:

| Extension | Case Rule | Used For |
|-----------|-----------|----------|
| `.jpg` | Lowercase | Most image types |
| `.jpeg` | Lowercase | Alternative JPEG extension |
| `.png` | Lowercase | Layer options, showroom |
| `.AVIF` | **Uppercase required** | Beltline (vehicleselector) images |
| `.json` | Lowercase | Linking record manifest |

Any other extensions are flagged as unauthorized. Lowercase `.avif` is flagged as a case violation.

## Asset Naming Conventions

### General Pattern
Filenames typically follow: `{viewtype_prefix}/{subdir}/{viewtype}_{angle}_{features}.{ext}`

Example: `ext/base/ext_21_bs-sa.jpg`

### Beltline Files
- Desktop: `vsd_{frame}_{features}.AVIF` (frames 0-71)
- Mobile: `vsm_{frame}_{features}.AVIF` (frames 49-71)

### MEC-Specific Files
- Files with `_mec` in the filename are only allowed in `2d-background` experienceCondition sections

### Layer Numbering
- Layer 0 = base image (no layer suffix needed)
- Layer N > 0 = overlay image; the layer number must appear as the last number before the file extension in the filename (e.g., `_21_20.png` means layer 20)

## Feature Codes

The `features` array on each record contains WERS (World Engineering Release System) codes that identify vehicle options:

- **`vs-` prefix**: Vehicle Series codes (e.g., `vs-kz`)
- **`acm` prefix**: ACM codes (e.g., `acm5b`)
- **`bs-` prefix**: Body style codes (e.g., `bs-sa`)
- **Other codes**: Paint colors, trim options, packages (e.g., `pn4hq`)

These codes are used by `check_series_permutations` and `extra_carousel_validation_check` to verify coverage completeness.