{"name":"OPF dynamic composition","description":"Slide.composition overrides layout composition defaults. Groups compose their blocks independently. Gap and padding are fractions of the container short edge. Text metrics are deterministic estimates; inspect final output with your fonts.","schema":{"type":"object","additionalProperties":false,"description":"Automatic slide and content-group arrangement. Nested content groups arrange their children independently, inheriting only minFontSize, maxFontSize and overflow. Explicit promoted regions retain their positions. A layout defines its grid as one ordered list of regions; its composition supports gap, padding, minFontSize, maxFontSize and overflow rather than mode, columns or weights.","properties":{"mode":{"type":"string","enum":["auto","grid","row","column"],"description":"auto chooses a grid from available space and content; grid uses columns; row and column use one horizontal or vertical track."},"columns":{"type":"integer","minimum":1,"maximum":12,"description":"Column count for grid. In auto mode this caps the number of columns."},"gap":{"type":"number","minimum":0,"maximum":0.1,"description":"Space between cells as a fraction of the container short edge (canvas at slide root). Default 0.03333333333333333."},"padding":{"type":"number","minimum":0,"maximum":0.2,"description":"Inset as a fraction of the container short edge. Default 0.08 on a slide, 0 inside a group."},"weights":{"type":"array","minItems":1,"maxItems":12,"items":{"type":"number","exclusiveMinimum":0,"maximum":100},"description":"Relative track sizes: columns for row/grid/auto, rows for column. Omitted tracks have weight 1; extra weights are ignored."},"minFontSize":{"type":"number","minimum":8,"maximum":32,"description":"Minimum readable text size in reference pixels at a 720-pixel canvas short edge. Default 16. Overflow is diagnosed when text cannot fit at this size."},"maxFontSize":{"type":"number","minimum":8,"maximum":200,"description":"Largest body text size in reference pixels at a 720-pixel canvas short edge: paragraphs, lists, quotes, metrics and timelines are never set larger, their growth included (headings, tables, code and charts keep their sizes). Never lowers text under minFontSize. paginate writes it on the pages after the first, so the pages of one slide share its type sizes."},"overflow":{"type":"string","enum":["warn","error"],"description":"warn returns diagnostics for content that does not fit; error rejects layout. Content is never silently removed. Default warn."}}},"contentSchema":{"type":"object","description":"A content leaf or recursively composed group. A group contains blocks and optional composition; it cannot mix blocks with leaf payload fields. Groups may nest up to 32 levels.","additionalProperties":false,"properties":{"id":{"type":"string","description":"Optional stable identifier for this payload, unique among slide and payload ids in the document. Use when another system needs to address the payload across edits — patch-style agent edits, comments, review state, or generation provenance. Identity survives reordering where array indexes do not.","examples":["kpi-adoption","churn-quote"]},"extensions":{"type":"object","description":"Custom data passthrough for agent workflows at payload scope; ignored by the engine but preserved across read/write round-trips."},"region":{"type":"string","pattern":"^[a-z][a-z0-9-]*$","description":"Pin a root block (slides.N.blocks.I) to a region of the slide's template layout by name (OPF 0.19). The block goes to that region when the region exists, accepts the block's kind and has room; otherwise the pin is ignored with a warning (opf/region-unknown, opf/region-kind or opf/region-full) and the block is placed by its kind. Blocks without a pin are bound by reading order, role and kind. A pin on a nested block, or on a slide without a template layout, has no effect.","examples":["notes","metrics"]},"type":{"type":"string","enum":["text","list","image","chart","table","video","code","metric","quote","timeline","diagram","group"],"description":"Optional content kind. When omitted, engines infer the kind from the fields present."},"text":{"oneOf":[{"type":"string"},{"type":"array","items":{"$ref":"#/$defs/TextRun"}}],"description":"Text payload. Use a string for plain text or TextRun[] for inline rich text. TextRun items may be plain strings or formatted run objects.","examples":["Hello, world",["Revenue grew ",{"text":"42%","bold":true,"color":"#16A34A"}," year over year."]]},"items":{"type":"array","items":{"$ref":"#/$defs/ListItem"},"description":"Structured list payload (type 'list'). Each item is either a plain string, a TextRun[] rich text sequence, or a ListItem object with optional `description`. List nesting uses item.level rather than nested content payloads. Use `items` when entries share a shape or any entry needs a `description`; use `bullets` for plain talking points. Both draw the same marker, nesting and numbering. A block or region holds `items` or `bullets`, never both, and `items` cannot sit beside `text`.","examples":[["Sub-second agent latency",["Drop-in compatible with ",{"text":"OpenAI tool-calling","bold":true}],{"text":"SOC 2 Type II","description":"Security review ready for enterprise procurement."}]]},"bullets":{"type":"array","items":{"$ref":"#/$defs/BulletItem"},"description":"Prose bullet payload: short talking points, each standing alone. Presence of this field infers type 'text', so it may sit beside `text` in one payload. Entries have no `description`; use `items` for entries with supporting detail.","examples":[["Sub-second agent latency","Drop-in compatible with OpenAI tool-calling","SOC 2 Type II"]]},"numbering":{"$ref":"#/$defs/NumberingSpec","description":"Number the payload's `items` or `bullets` instead of bulleting them. A style name (arabic, roman-upper, roman-lower, alpha-upper, alpha-lower) or a Numbering object applies to every list level; an array gives one entry per level (index = level, the last entry repeats for deeper levels). Counting follows PowerPoint: consecutive entries of one level count up from its start, and an entry of a shallower level restarts the deeper levels. Absent = bullets. Valid only with `items` or `bullets`. Native PowerPoint export writes a:buAutoNum with the matching scheme and startAt; the preview draws the same numbers at the same marker geometry.","examples":["arabic","roman-lower",{"style":"alpha-upper","start":3,"suffix":"paren"},["arabic","alpha-lower",{"style":"roman-lower","suffix":"paren-both"}]]},"columns":{"oneOf":[{"const":"auto"},{"type":"integer","minimum":1,"maximum":3}],"description":"Lay the payload's `items` or `bullets` out in columns (OPF 0.19). 'auto' tries 1, 2 then 3 equal columns at the starting text size and uses the first count at which the list fits, as long as a column stays at least a quarter of the slide wide; when none fits, the largest allowed count shrinks towards minFontSize. A list of 6 or fewer entries is never split by 'auto'; it shrinks in one column. 1, 2 or 3 fixes the count. Column breaks fall between items (a nested item stays with its parent) and keep the columns as even as possible; numbering continues and reading order runs column by column. A lone list in a layout region with listColumns: 'auto' behaves as 'auto'.","examples":["auto",2]},"image":{"$ref":"#/$defs/Asset","description":"Source for an image item.","examples":["https://cdn.acme.com/images/diagram.png","data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9V3iWggAAAAASUVORK5CYII=","./images/diagram.png","asset:img-diagram"]},"fit":{"type":"string","enum":["cover","contain","stretch","auto"],"description":"Image payloads only. How the picture fills its frame: 'cover' fills it and crops what overflows around focus; 'contain' shows the whole picture, in a frame of its own proportions placed at the region's anchor (top by default); 'stretch' scales it to the frame exactly; 'auto' covers when the crop keeps at least 85% of the picture's width or height and contains otherwise (an SVG, or a picture whose size cannot be read from the document, is contained), so a photo close to its frame's shape fills it and any other is shown whole. Default: the effective design.imageFit, else 'cover' in a layout and 'contain' on a slide with no layout."},"focus":{"$ref":"#/$defs/ImageFocus","description":"Image payloads only. Point of the picture to keep in view when 'cover' crops it. Ignored by the other fits. Without a focus a portrait picture (taller than wide) cropped into a wider frame keeps y 0.3 so heads stay in frame; every other crop is centered."},"aspectRatio":{"type":"number","exclusiveMinimum":0,"maximum":10,"description":"Image payloads only. Width-to-height ratio of the frame: the frame becomes the largest centered box with this ratio inside the block's region, for example 2.39 for a cinematic letterbox or 0.5 for a phone-shaped frame. shape 'circle' always uses 1."},"shape":{"type":"string","enum":["rectangle","rounded","circle","hexagon"],"description":"Image payloads only. Mask applied to the frame, exported as the picture's native preset geometry (rect, roundRect, ellipse, hexagon). 'circle' makes the frame square. Default 'rectangle'."},"cornerRadius":{"type":"number","minimum":0,"maximum":0.5,"description":"Image payloads only. Corner radius for shape 'rounded' as a fraction of the frame's shorter side. Default 0.16667, PowerPoint's roundRect default."},"border":{"$ref":"#/$defs/ImageBorder","description":"Image payloads only. Line along the frame's shape."},"opacity":{"type":"number","minimum":0,"maximum":1,"description":"Image payloads only. Picture opacity from 0 to 1, exported as a native alphaModFix. The border and overlay keep their own opacity. Default 1."},"recolor":{"$ref":"#/$defs/ImageRecolor","description":"Image payloads only. Grayscale or duotone treatment of the picture's pixels."},"overlay":{"$ref":"#/$defs/Overlay","description":"Image payloads only. Scrim over the picture in the frame's shape, or a band along one edge of a rectangle frame."},"placement":{"$ref":"#/$defs/ImagePlacement","description":"Image payloads only, and only on a top-level block (slides.N.blocks.I), at most one per edge. Bleeds the image to one slide edge; the headings and the other blocks compose in the rest of the slide."},"video":{"$ref":"#/$defs/Asset","description":"Source for a video item. Engines do not play video: the preview draws a placeholder (a play badge with the asset's title or source as its caption), and PPTX export draws the same placeholder as native shapes linked to an http(s) source, with no embedded media. Native playback is out of scope (docs/programs/release-readiness).","examples":["asset:demo-video","./media/demo.mp4"]},"chart":{"$ref":"#/$defs/Chart","description":"Chart payload. Presence of this field infers type 'chart'."},"table":{"$ref":"#/$defs/Table","description":"Table payload. Presence of this field infers type 'table'."},"code":{"oneOf":[{"type":"string"},{"$ref":"#/$defs/Code"}],"description":"Code payload. A string is shorthand for { \"source\": value }; object form carries optional syntax language and filename metadata.","examples":["def greet(name: str) -> str:\n    return f\"Hello, {name}!\"",{"source":"export function greet(name: string) {\n  return `Hello, ${name}`;\n}","language":"ts","filename":"greet.ts"}]},"metric":{"oneOf":[{"type":"string"},{"type":"number"},{"$ref":"#/$defs/Metric"}],"description":"Metric payload. A string or number is shorthand for { \"value\": value }; object form carries optional label, description, unit, delta, trend, and sentiment metadata. Numeric values remain numbers; renderers format them for display.","examples":["98%",42,{"value":"$12.4M","label":"Revenue","description":"Recognized revenue for the quarter.","delta":"+12%","trend":"up"}]},"quote":{"oneOf":[{"type":"string"},{"$ref":"#/$defs/Quote"}],"description":"Quote payload. A string is shorthand for { \"text\": value }; object form carries optional attribution, role, photo and source metadata.","examples":["This changed how our team handles reviews.",{"text":"This changed how our team handles reviews.","attribution":"VP Operations, Acme Corp","source":"Customer interview, March 2026"}]},"timeline":{"$ref":"#/$defs/Timeline","description":"Timeline payload ordered by narrative or chronology.","examples":[[{"when":"2026-01","what":"Pilot","description":"Launch with the first operations team."},{"when":"2026-04","what":"Rollout","description":"Expand to all regions."}],{"name":"Rollout Plan","description":"Major milestones for the regional rollout.","events":[{"when":"Q1","what":"Pilot"},{"when":"Q2","what":"Rollout"}]}]},"diagram":{"oneOf":[{"type":"string"},{"$ref":"#/$defs/Diagram"}],"description":"Diagram payload: Mermaid source (flowchart, sequence, state, class, ER, mindmap, timeline, journey, C4, architecture and the other built-in Mermaid families) drawn in the deck's fonts and colors. A string is shorthand for { \"source\": value }; object form carries the source syntax and a text alternative. Presence of this field infers type 'diagram'.","examples":["flowchart LR\n  A[Brief] --> B{Approved?}\n  B -->|yes| C[Build]\n  B -->|no| A",{"source":"sequenceDiagram\n  Client->>API: POST /decks\n  API-->>Client: 201 Created","alt":"The client creates a deck and the API answers 201 Created."}]},"caption":{"$ref":"#/$defs/Caption","description":"Caption for an image, chart, table, video or diagram payload, composed inside the block's region (below the media by default). Invalid on other payload kinds and on groups."},"blocks":{"type":"array","minItems":1,"items":{"$ref":"#/$defs/ContentPayload"},"description":"Ordered children of a group. Each child is a leaf or another group."},"composition":{"$ref":"#/$defs/Composition","description":"Arrangement within this group. Only minFontSize, maxFontSize and overflow inherit from the parent; strict overflow cannot be weakened."},"emphasis":{"type":"boolean","description":"true draws this block or group on the slide's emphasis surface: a contrasting card in its cell (a dark card on a light slide, an accent card on a dark one), from the deck's own scheme slots, with every text color on it at 4.5:1 or more against its fill. A slide has one emphasis surface: the first block or group with emphasis: true in reading order takes it, and any other is drawn without it (composition diagnostic emphasis-ignored). Without any, a slide's short last text block (60 characters or fewer) after longer blocks is drawn as a band at the foot of the body, and one of 30 or fewer after a lone long text as a pill right under that text; neither is drawn where it would cost another block its fitted size. Without any either, the second card of a before-and-after or problem-and-solution pair, or the one tier of a set marked recommended or most popular, takes the surface and the other cards of the pair or set are drawn on plain cards (read from the blocks' labels and short texts, never from ids). false keeps a block out of those automatic rules.","examples":[true,false]}},"allOf":[{"if":{"required":["type"],"properties":{"type":{"const":"list"}}},"then":{"required":["items"]}},{"if":{"required":["type"],"properties":{"type":{"const":"image"}}},"then":{"required":["image"]}},{"if":{"required":["type"],"properties":{"type":{"const":"chart"}}},"then":{"required":["chart"]}},{"if":{"required":["type"],"properties":{"type":{"const":"table"}}},"then":{"required":["table"]}},{"if":{"required":["type"],"properties":{"type":{"const":"video"}}},"then":{"required":["video"]}},{"if":{"required":["type"],"properties":{"type":{"const":"code"}}},"then":{"required":["code"]}},{"if":{"required":["type"],"properties":{"type":{"const":"metric"}}},"then":{"required":["metric"]}},{"if":{"required":["type"],"properties":{"type":{"const":"quote"}}},"then":{"required":["quote"]}},{"if":{"required":["type"],"properties":{"type":{"const":"timeline"}}},"then":{"required":["timeline"]}},{"if":{"required":["type"],"properties":{"type":{"const":"diagram"}}},"then":{"required":["diagram"]}},{"if":{"required":["type"],"properties":{"type":{"const":"group"}}},"then":{"required":["blocks"]}},{"if":{"required":["composition"]},"then":{"required":["blocks"]}},{"if":{"required":["blocks"]},"then":{"properties":{"type":{"const":"group"}},"not":{"anyOf":[{"required":["text"]},{"required":["items"]},{"required":["bullets"]},{"required":["image"]},{"required":["video"]},{"required":["chart"]},{"required":["table"]},{"required":["code"]},{"required":["metric"]},{"required":["quote"]},{"required":["timeline"]},{"required":["diagram"]}]}}},{"if":{"required":["columns"]},"then":{"anyOf":[{"required":["items"]},{"required":["bullets"]}]}}]},"nesting":{"maxDepth":32,"inherited":["minFontSize","overflow"],"groupPaddingDefault":0},"examples":[{"$schema":"https://openpresentation.org/schema/opf/v1","name":"auto composition","slides":[{"title":"Content with room to breathe","composition":{"mode":"auto"},"blocks":[{"text":"State the decision."},{"text":"Show the evidence."},{"text":"Name the next step."}]}]},{"$schema":"https://openpresentation.org/schema/opf/v1","name":"row composition","slides":[{"title":"Content with room to breathe","composition":{"mode":"row"},"blocks":[{"text":"State the decision."},{"text":"Show the evidence."},{"text":"Name the next step."}]}]},{"$schema":"https://openpresentation.org/schema/opf/v1","name":"column composition","slides":[{"title":"Content with room to breathe","composition":{"mode":"column"},"blocks":[{"text":"State the decision."},{"text":"Show the evidence."},{"text":"Name the next step."}]}]},{"$schema":"https://openpresentation.org/schema/opf/v1","name":"grid composition","slides":[{"title":"Content with room to breathe","composition":{"mode":"grid"},"blocks":[{"text":"State the decision."},{"text":"Show the evidence."},{"text":"Name the next step."}]}]}]}