ford_qc/documentation/02-data-model.md

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

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.

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.