From c5e41d047461bfb8055cd884c39db370f95c3edf Mon Sep 17 00:00:00 2001
From: Brian O'Kelley <bokelley@scope3.com>
Date: Fri, 1 Aug 2025 11:37:12 +0200
Subject: [PATCH] feat: add frame-based structure for multi-asset creative
 formats
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Introduce frame-based format structure for carousels and slideshows
- Update foundational_product_carousel to use min_frames/max_frames
- Add NYTimes slideshow format example with proper desktop-only sizing
- Add documentation explaining frame-based format structure
- Use "frame" terminology for consistency with existing slider formats

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/media-buy/creative-formats.md      | 46 ++++++++++++
 static/schemas/creative-formats-v1.json | 93 ++++++++++++++++++++++++-
 2 files changed, 136 insertions(+), 3 deletions(-)

diff --git a/docs/media-buy/creative-formats.md b/docs/media-buy/creative-formats.md
index 7f1e87d7a8..93d23b34b3 100644
--- a/docs/media-buy/creative-formats.md
+++ b/docs/media-buy/creative-formats.md
@@ -40,6 +40,52 @@ The JSON schema includes:
 - Breaking changes will increment the major version
 - Implementations should check the `version` field
 
+### Frame-Based Formats
+
+Some formats support multiple frames, where each frame contains a collection of assets that are displayed together. This is particularly useful for carousel, slideshow, and story-like formats.
+
+#### Frame Structure
+
+Frame-based formats use the following structure:
+
+```json
+{
+  "specs": {
+    "min_frames": 3,
+    "max_frames": 10,
+    "frame_schema": {
+      "assets": [
+        {
+          "type": "image",
+          "id": "primary_image",
+          "size": "600x600",
+          "file_types": ["jpg", "png"],
+          "required": true
+        },
+        {
+          "type": "text",
+          "id": "headline",
+          "max_characters": 100,
+          "required": true
+        }
+      ]
+    },
+    "global_assets": [
+      {
+        "type": "image",
+        "id": "logo",
+        "file_types": ["png", "svg"],
+        "requirements": "Transparent background"
+      }
+    ]
+  }
+}
+```
+
+- **min_frames/max_frames**: Defines the allowed range of frames
+- **frame_schema**: Defines assets that must be provided for each frame
+- **global_assets**: Assets that apply to the entire format (logos, CTAs, etc.)
+
 #### Standard Video Formats
 
 ##### video_standard_1080p
diff --git a/static/schemas/creative-formats-v1.json b/static/schemas/creative-formats-v1.json
index 070d3ebbbf..09a073d4f6 100644
--- a/static/schemas/creative-formats-v1.json
+++ b/static/schemas/creative-formats-v1.json
@@ -195,9 +195,35 @@
         "category": "foundational",
         "description": "Multi-product interactive carousel",
         "specs": {
-          "products": "3-10",
-          "image_sizes": ["627x627", "1200x627"],
-          "per_product_data": ["name", "price", "url"],
+          "min_frames": 3,
+          "max_frames": 10,
+          "frame_schema": {
+            "assets": [
+              {
+                "type": "image",
+                "id": "product_image",
+                "sizes": ["627x627", "1200x627"],
+                "file_types": ["jpg", "png", "webp"]
+              },
+              {
+                "type": "text",
+                "id": "product_name",
+                "required": true
+              },
+              {
+                "type": "text",
+                "id": "product_price",
+                "format": "currency",
+                "required": true
+              },
+              {
+                "type": "url",
+                "id": "product_url",
+                "format": "https",
+                "required": true
+              }
+            ]
+          },
           "interaction": "swipe/click navigation"
         },
         "publisher_coverage": "7+ major publishers",
@@ -259,6 +285,67 @@
           }
         },
         "is_3p_served": false
+      },
+      "nytimes_slideshow_flex_xl_desktop": {
+        "format_id": "display_slideshow_flex_xl_desktop_1125x600",
+        "extends": "foundational_product_carousel",
+        "publisher": "nytimes",
+        "type": "display",
+        "description": "Split screen slideshow format for multi-part image-led storytelling on desktop (1125x600 breakpoint)",
+        "width": 1125,
+        "height": 600,
+        "platform": "desktop",
+        "file_types": ["jpg", "png"],
+        "is_standard": false,
+        "is_3p_served": false,
+        "specs": {
+          "min_frames": 3,
+          "max_frames": 5,
+          "frame_schema": {
+            "assets": [
+              {
+                "type": "image",
+                "id": "primary_image",
+                "size": "600x600",
+                "file_types": ["jpg", "png"],
+                "requirements": "Must be free of text, logo or branding"
+              },
+              {
+                "type": "text",
+                "id": "headline",
+                "max_characters": 100,
+                "required": true
+              },
+              {
+                "type": "text",
+                "id": "descriptor_message",
+                "max_characters": 210,
+                "required": true
+              }
+            ]
+          },
+          "global_assets": [
+            {
+              "type": "text",
+              "id": "cta_message",
+              "max_characters": 15,
+              "required": true
+            },
+            {
+              "type": "image",
+              "id": "logo",
+              "file_types": ["png", "eps"],
+              "requirements": "Transparent background required"
+            },
+            {
+              "type": "url",
+              "id": "click_through_url",
+              "format": "https",
+              "required": true
+            }
+          ]
+        },
+        "source_url": "https://advertising.nytimes.com/formats/display-formats/slideshow-flex-xl/"
       }
     }
   },