Content Payload

Metadata

Definition

#/$defs/ContentPayload

Form

object · 13 combined constraints (allOf)

Source

spec/schemas/opf.schema.json

Field index

id

typestringrequirednodefault—

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.

{
  "id": "kpi-adoption"
}

extensions

typeobjectrequirednodefault—

Custom data passthrough for agent workflows at payload scope; ignored by the engine but preserved across read/write round-trips.

region

typestringrequirednodefault—pattern^[a-z][a-z0-9-]*$

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.

{
  "region": "notes"
}

type

typeenumrequirednodefault—

Optional content kind. When omitted, engines infer the kind from the fields present.

type · Allowed values

"text""list""image""chart""table""video""code""metric""quote""timeline""group"

{
  "type": "text"
}

text

typestring | array<ref:TextRun>requirednodefault—

Text payload. Use a string for plain text or TextRun[] for inline rich text. TextRun items may be plain strings or formatted run objects.

{
  "text": "Hello, world"
}

items

typearray<ref:ListItem>requirednodefault—

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.

{
  "items": [
    "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

typearray<ref:BulletItem>requirednodefault—

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.

{
  "bullets": [
    "Sub-second agent latency",
    "Drop-in compatible with OpenAI tool-calling",
    "SOC 2 Type II"
  ]
}

numbering

typeref:NumberingSpecrequirednodefault—

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.

numbering · Named choices (see schema for other values and constraints)

"arabic""roman-upper""roman-lower""alpha-upper""alpha-lower"

numbering (oneOf 2).style · Allowed values

"arabic""roman-upper""roman-lower""alpha-upper""alpha-lower"

numbering (oneOf 2).suffix · Allowed values

"period""paren""paren-both"

numbering (oneOf 3)[] · Named choices (see schema for other values and constraints)

"arabic""roman-upper""roman-lower""alpha-upper""alpha-lower"

{
  "numbering": "arabic"
}

columns

typeconst | integerrequirednodefault—

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. 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'.

columns · Named choices (see schema for other values and constraints)

"auto"

{
  "columns": "auto"
}

image

typeref:Assetrequirednodefault—

Source for an image item.

{
  "image": "https://cdn.acme.com/images/diagram.png"
}

fit

typeenumrequirednodefault—

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. Default: the effective design.imageFit, else 'cover' in a layout and 'contain' on a slide with no layout.

fit · Allowed values

"cover""contain""stretch"

{
  "fit": "cover"
}

focus

typeref:ImageFocusrequirednodefault—

Image payloads only. Point of the picture to keep in view when 'cover' crops it. Ignored by the other fits.

aspectRatio

typenumberrequirednodefault—

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

typeenumrequirednodefault—

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'.

shape · Allowed values

"rectangle""rounded""circle""hexagon"

{
  "shape": "rectangle"
}

cornerRadius

typenumberrequirednodefault—

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

typeref:ImageBorderrequirednodefault—

Image payloads only. Line along the frame's shape.

border.color · Named choices (see schema for other values and constraints)

"accent1""accent2""accent3""accent4""accent5""accent6""dark1""dark2""light1""light2""hyperlink""followedHyperlink""primary""secondary""accent""background""surface""surfaceAlt""text""textSecondary"

opacity

typenumberrequirednodefault—

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

typeref:ImageRecolorrequirednodefault—

Image payloads only. Grayscale or duotone treatment of the picture's pixels.

recolor · Named choices (see schema for other values and constraints)

"grayscale"

recolor (oneOf 2).dark · Named choices (see schema for other values and constraints)

"accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"

recolor (oneOf 2).light · Named choices (see schema for other values and constraints)

"accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"

overlay

typeref:Overlayrequirednodefault—

Image payloads only. Scrim over the picture in the frame's shape, or a band along one edge of a rectangle frame.

overlay.color · Named choices (see schema for other values and constraints)

"accent1""accent2""accent3""accent4""accent5""accent6""dark1""dark2""light1""light2""hyperlink""followedHyperlink""primary""secondary""accent""background""surface""surfaceAlt""text""textSecondary"

overlay.edge · Allowed values

"top""bottom""left""right"

placement

typeref:ImagePlacementrequirednodefault—

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.

placement.edge · Allowed values

"left""right""top""bottom"

video

typeref:Assetrequirednodefault—

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).

{
  "video": "asset:demo-video"
}

chart

typeref:Chartrequirednodefault—

Chart payload. Presence of this field infers type 'chart'.

chart.type · Allowed values

"100pct-stacked-area", "100pct-stacked-bar", "100pct-stacked-column", "area", "bar", "box-and-whisker", "column", "combo", "doughnut", "filled-radar", "funnel", "histogram", "line", "line-with-markers", "pareto", "pie", "radar", "radar-with-markers", "scatter", "stacked-area", "stacked-bar", "stacked-column", "stacked-line", "stacked-line-with-markers", "treemap", "waterfall", "world"

chart.legend · Allowed values

"none", "top", "bottom", "left", "right"

chart.dataLabels (oneOf 2).content[] · Allowed values

"value", "percent", "category"

chart.dataLabels (oneOf 2).position · Allowed values

"auto", "center", "inside-end", "inside-base", "outside-end", "above", "below", "left", "right"

chart.colors[] · Named choices (see schema for other values and constraints)

"accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"

table

typeref:Tablerequirednodefault—

Table payload. Presence of this field infers type 'table'.

table.columns[] (oneOf 3).style.fill · Named choices (see schema for other values and constraints)

"accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"

table.columns[] (oneOf 3).style.color · Named choices (see schema for other values and constraints)

"accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"

table.columns[] (oneOf 3).style.align · Allowed values

"left", "center", "right"

table.columns[] (oneOf 3).style.verticalAlign · Allowed values

"top", "middle", "bottom"

table.columns[] (oneOf 3).style.borders.top.color · Named choices (see schema for other values and constraints)

"accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"

table.columns[] (oneOf 3).style.borders.top.dash · Allowed values

"solid", "dash", "dot"

code

typestring | ref:Coderequirednodefault—

Code payload. A string is shorthand for { "source": value }; object form carries optional syntax language and filename metadata.

{
  "code": "def greet(name: str) -> str:\n    return f\"Hello, {name}!\""
}

metric

typestring | number | ref:Metricrequirednodefault—

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.

metric (oneOf 3).trend · Allowed values

"up""down""flat"

metric (oneOf 3).sentiment · Allowed values

"positive""negative""neutral"

{
  "metric": "98%"
}

quote

typestring | ref:Quoterequirednodefault—

Quote payload. A string is shorthand for { "text": value }; object form carries optional attribution, role, photo and source metadata.

{
  "quote": "This changed how our team handles reviews."
}

timeline

typeref:Timelinerequirednodefault—

Timeline payload ordered by narrative or chronology.

timeline (oneOf 1)[].status · Allowed values

"done""current""planned"

{
  "timeline": [
    {
      "when": "2026-01",
      "what": "Pilot",
      "description": "Launch with the first operations team."
    },
    {
      "when": "2026-04",
      "what": "Rollout",
      "description": "Expand to all regions."
    }
  ]
}

caption

typeref:Captionrequirednodefault—

Caption for an image, chart, table or video payload, composed inside the block's region (below the media by default). Invalid on other payload kinds and on groups.

caption (oneOf 3).position · Allowed values

"below""above"

caption (oneOf 3).align · Allowed values

"left""center""right"

blocks

typearray<ref:ContentPayload>requirednodefault—

Ordered children of a group. Each child is a leaf or another group.

blocks[].type · Allowed values

"text", "list", "image", "chart", "table", "video", "code", "metric", "quote", "timeline", "group"

blocks[].numbering · Named choices (see schema for other values and constraints)

"arabic", "roman-upper", "roman-lower", "alpha-upper", "alpha-lower"

blocks[].numbering (oneOf 2).style · Allowed values

"arabic", "roman-upper", "roman-lower", "alpha-upper", "alpha-lower"

blocks[].numbering (oneOf 2).suffix · Allowed values

"period", "paren", "paren-both"

blocks[].numbering (oneOf 3)[] · Named choices (see schema for other values and constraints)

"arabic", "roman-upper", "roman-lower", "alpha-upper", "alpha-lower"

blocks[].columns · Named choices (see schema for other values and constraints)

"auto"

blocks[].fit · Allowed values

"cover", "contain", "stretch"

blocks[].shape · Allowed values

"rectangle", "rounded", "circle", "hexagon"

blocks[].border.color · Named choices (see schema for other values and constraints)

"accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"

blocks[].recolor · Named choices (see schema for other values and constraints)

"grayscale"

blocks[].recolor (oneOf 2).dark · Named choices (see schema for other values and constraints)

"accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"

blocks[].recolor (oneOf 2).light · Named choices (see schema for other values and constraints)

"accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"

blocks[].overlay.color · Named choices (see schema for other values and constraints)

"accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"

blocks[].overlay.edge · Allowed values

"top", "bottom", "left", "right"

blocks[].placement.edge · Allowed values

"left", "right", "top", "bottom"

blocks[].chart.type · Allowed values

"100pct-stacked-area", "100pct-stacked-bar", "100pct-stacked-column", "area", "bar", "box-and-whisker", "column", "combo", "doughnut", "filled-radar", "funnel", "histogram", "line", "line-with-markers", "pareto", "pie", "radar", "radar-with-markers", "scatter", "stacked-area", "stacked-bar", "stacked-column", "stacked-line", "stacked-line-with-markers", "treemap", "waterfall", "world"

blocks[].chart.legend · Allowed values

"none", "top", "bottom", "left", "right"

blocks[].chart.dataLabels (oneOf 2).content[] · Allowed values

"value", "percent", "category"

blocks[].chart.dataLabels (oneOf 2).position · Allowed values

"auto", "center", "inside-end", "inside-base", "outside-end", "above", "below", "left", "right"

blocks[].chart.colors[] · Named choices (see schema for other values and constraints)

"accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"

blocks[].table.columns[] (oneOf 3).style.fill · Named choices (see schema for other values and constraints)

"accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"

blocks[].table.columns[] (oneOf 3).style.color · Named choices (see schema for other values and constraints)

"accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"

blocks[].table.columns[] (oneOf 3).style.align · Allowed values

"left", "center", "right"

blocks[].table.columns[] (oneOf 3).style.verticalAlign · Allowed values

"top", "middle", "bottom"

blocks[].table.columns[] (oneOf 3).style.borders.top.color · Named choices (see schema for other values and constraints)

"accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"

blocks[].table.columns[] (oneOf 3).style.borders.top.dash · Allowed values

"solid", "dash", "dot"

blocks[].metric (oneOf 3).trend · Allowed values

"up", "down", "flat"

blocks[].metric (oneOf 3).sentiment · Allowed values

"positive", "negative", "neutral"

blocks[].timeline (oneOf 1)[].status · Allowed values

"done", "current", "planned"

blocks[].caption (oneOf 3).position · Allowed values

"below", "above"

blocks[].caption (oneOf 3).align · Allowed values

"left", "center", "right"

blocks[].composition.mode · Allowed values

"auto", "grid", "row", "column"

blocks[].composition.overflow · Allowed values

"warn", "error"

composition

typeref:Compositionrequirednodefault—

Arrangement within this group. Only minFontSize and overflow inherit from the parent; strict overflow cannot be weakened.

composition.mode · Allowed values

"auto""grid""row""column"

composition.overflow · Allowed values

"warn""error"

allOf 1 · object

{
  "if": {
    "required": [
      "type"
    ],
    "properties": {
      "type": {
        "const": "list"
      }
    }
  },
  "then": {
    "required": [
      "items"
    ]
  }
}

allOf 2 · object

{
  "if": {
    "required": [
      "type"
    ],
    "properties": {
      "type": {
        "const": "image"
      }
    }
  },
  "then": {
    "required": [
      "image"
    ]
  }
}

allOf 3 · object

{
  "if": {
    "required": [
      "type"
    ],
    "properties": {
      "type": {
        "const": "chart"
      }
    }
  },
  "then": {
    "required": [
      "chart"
    ]
  }
}

allOf 4 · object

{
  "if": {
    "required": [
      "type"
    ],
    "properties": {
      "type": {
        "const": "table"
      }
    }
  },
  "then": {
    "required": [
      "table"
    ]
  }
}

allOf 5 · object

{
  "if": {
    "required": [
      "type"
    ],
    "properties": {
      "type": {
        "const": "video"
      }
    }
  },
  "then": {
    "required": [
      "video"
    ]
  }
}

allOf 6 · object

{
  "if": {
    "required": [
      "type"
    ],
    "properties": {
      "type": {
        "const": "code"
      }
    }
  },
  "then": {
    "required": [
      "code"
    ]
  }
}

allOf 7 · object

{
  "if": {
    "required": [
      "type"
    ],
    "properties": {
      "type": {
        "const": "metric"
      }
    }
  },
  "then": {
    "required": [
      "metric"
    ]
  }
}

allOf 8 · object

{
  "if": {
    "required": [
      "type"
    ],
    "properties": {
      "type": {
        "const": "quote"
      }
    }
  },
  "then": {
    "required": [
      "quote"
    ]
  }
}

allOf 9 · object

{
  "if": {
    "required": [
      "type"
    ],
    "properties": {
      "type": {
        "const": "timeline"
      }
    }
  },
  "then": {
    "required": [
      "timeline"
    ]
  }
}

allOf 10 · object

{
  "if": {
    "required": [
      "type"
    ],
    "properties": {
      "type": {
        "const": "group"
      }
    }
  },
  "then": {
    "required": [
      "blocks"
    ]
  }
}

allOf 11 · object

{
  "if": {
    "required": [
      "composition"
    ]
  },
  "then": {
    "required": [
      "blocks"
    ]
  }
}

allOf 12 · object

{
  "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"
          ]
        }
      ]
    }
  }
}

allOf 13 · object

{
  "if": {
    "required": [
      "columns"
    ]
  },
  "then": {
    "anyOf": [
      {
        "required": [
          "items"
        ]
      },
      {
        "required": [
          "bullets"
        ]
      }
    ]
  }
}