Asset Model Reference

This page documents all properties of the Asset model used for product images, documents, and media files.

Asset Properties

URL Properties

File Properties

Upload Control

Metadata

Key Concepts

AssetId

The AssetId is a unique identifier for each asset. If not provided during creation, a GUID is automatically generated:

{
  "assetId": "product-image-001"
}

URL Handling

Assets support two URL properties that work together:

{
  "externalUrl": "https://supplier.com/images/product.jpg",
  "url": null
}

After processing:

{
  "externalUrl": "https://supplier.com/images/product.jpg",
  "url": "https://cdn.example.com/products/product.jpg"
}

Link-only assets (ExternalCertification)

Set AssetType to ExternalCertification for images that should stay at their source instead of being copied into Omnium storage, such as certification and labelling marks that many products share and that the issuing body may update. For these assets:

• Nothing is downloaded. Url is set to the same value as ExternalUrl, so consumers that read Url keep working.
• ForceUpload is ignored and reset to false.
• IsMainImage is ignored and reset to false. A link-only asset is never the main product image.
• Changing ExternalUrl moves Url along with it. No re-upload happens.
• Deleting the asset removes it from the product only. Nothing is deleted from storage.

Because the image is served from the external host, a change at the source shows on every product that references it without a new import. Use an https URL; browsers block http images on an https page.

{
  "assetId": "grontpunkt",
  "assetType": "ExternalCertification",
  "externalUrl": "https://marks.example.org/grontpunkt.png",
  "name": "Grønt Punkt",
  "altText": "Grønt Punkt",
  "sortOrder": 100
}

After saving, Url equals ExternalUrl. Changing an already uploaded asset to ExternalCertification switches Url to the external URL; the copy previously stored in Omnium is not removed.

IsMainImage

The IsMainImage flag designates the primary product image:

• Only one asset per product should have IsMainImage: true
• The main image URL is synchronized to Product.MainImageUrl
• Main image is typically shown in product listings and search results

{
  "assets": [
    {
      "assetId": "product-image-001",
      "externalUrl": "https://example.com/front.jpg",
      "isMainImage": true
    },
    {
      "assetId": "product-image-002",
      "externalUrl": "https://example.com/back.jpg",
      "isMainImage": false
    }
  ]
}

Purpose

The Purpose property categorizes assets by their intended use:

Configure valid purpose values in tenant settings via AssetPurposeKeys.

SortOrder

Control asset display order with SortOrder:

{
  "assets": [
    { "assetId": "product-image-001", "sortOrder": 1 },
    { "assetId": "product-image-002", "sortOrder": 2 },
    { "assetId": "product-image-003", "sortOrder": 3 }
  ]
}

Lower values appear first. Assets without SortOrder typically appear last.

Custom Properties

The Properties list allows storing arbitrary key-value metadata:

{
  "assetId": "product-image-004",
  "properties": [
    { "key": "photographer", "value": "John Smith" },
    { "key": "shootDate", "value": "2024-01-15" },
    { "key": "copyright", "value": "2024 Acme Corp" },
    { "key": "color", "value": "blue" }
  ]
}

Use cases:

• Image credits and copyright
• Color/variant associations
• Campaign or season tagging
• Custom filtering criteria

Complete Example

{
  "assetId": "product-image-005",
  "assetType": "image",
  "name": "Front View",
  "description": "Blue cotton shirt - front view",
  "altText": "Blue cotton button-down shirt, front view",
  "purpose": "gallery",
  "sortOrder": 1,
  "isMainImage": true,
  "externalUrl": "https://supplier.com/images/shirt-001-front.jpg",
  "url": "https://cdn.example.com/products/shirt-001-front.jpg",
  "fileName": "shirt-001-front.jpg",
  "contentType": "image/jpeg",
  "length": 245678,
  "container": "products",
  "properties": [
    { "key": "variant", "value": "blue" },
    { "key": "angle", "value": "front" }
  ],
  "created": "2024-01-15T10:30:00Z",
  "modified": "2024-01-15T10:30:00Z"
}