Overlay Shape
An entry of slide 'shapes', drawn over the composed slide above the content and the furniture, later entries on top; it never moves content. An entry with 'connector' is a connector between two blocks or overlay shapes: it takes only 'id', 'connector', 'adjust', 'stroke', 'alt', 'decorative', 'hidden' and 'extensions'; core routes it as PowerPoint's own connector presets and PPTX export writes a native p:cxnSp glued to the shapes at its ends, so it follows them when they are moved in PowerPoint. Any other entry is an overlay shape: the shape block vocabulary (geometry, paint, effects, transform, text, accessibility) and exactly one placement, 'x', 'y', 'width' and 'height' (fractions of the slide) or 'at' (against a block, so it follows the block wherever composition puts it); PPTX export writes a native p:sp.
Metadata
Field index
| Field | Type | Req. | Description |
|---|---|---|---|
| id | string | — | Optional stable identifier, unique among slide, payload and overlay ids in the document. A connector names it in 'from' or 'to'. |
| x | ref:FiniteNumber | — | The shape's start edge as a signed fraction of the slide width, measured from the slide's start edge: the left edge in a left-to-right deck, the right edge in a right-to-left one. A shape sits over the layout, and the layout mirrors, so this coordinate is logical; only the position mirrors, never the geometry (an arrow keeps the way it points). Negative values or values greater than 1 place the shape partly or wholly outside the slide. With 'y', 'width' and 'height'. |
| y | ref:FiniteNumber | — | Top edge as a signed fraction of the slide height, from the top edge. Negative values or values greater than 1 place the shape partly or wholly outside the slide. |
| width | number | — | Width as a fraction of the slide width, from 0 (a vertical line) up to 8. Above 1 the shape is wider than the slide, for a circle or band that bleeds off it; the slide crops what lies outside. |
| height | number | — | Height as a fraction of the slide height, from 0 (a horizontal line) up to 8. Above 1 the shape is taller than the slide. |
| at | ref:OverlayAnchor | — | |
| layer | enum | — | Overlay shapes only. front (the default) draws the shape over the slide: above the content and the furniture. back draws it behind the slide: above the background and the watermark, below the content and the furniture (a panel or band behind a block). Array order stacks the shapes within each layer. Connectors are always in front.
|
| connector | ref:Connector | — | Makes the entry a connector: what it joins and how it runs. |
| shape | ref:ShapePreset | — | The preset geometry, as on a shape block. Default rect.
|
| path | ref:ShapePath | — | Custom geometry instead of a preset (a:custGeom), as on a shape block. |
| adjust | object | — | The preset's adjust handles (a:avLst) in OPF units, as on a shape block. On a connector, the adjust values of its connector preset (adj1 of an elbow or a curve between sites on one axis, a fraction of the frame's width), which replace the automatic route's, so a route made in PowerPoint is kept exactly. |
| fill | ref:ShapeFill | — | 'none', a ColorRef, { gradient } or { pattern }. Default the style's fill.
|
| opacity | number | — | The fill's opacity (a:alpha). Default 1. |
| stroke | ref:Stroke | — | A shape's line along its outline (default the style's line), or a connector's line: color, width, dash, compound, sketch and arrowheads ('start' at 'from', 'end' at 'to'; default a 2-pixel line in the slide's text color with no arrowheads).
|
| style | enum | — | The theme shape style, as on a shape block. Default moderate.
|
| shadow | ref:Shadow | — | Outer shadow.
|
| innerShadow | ref:InnerShadow | — | Inner shadow. |
| glow | ref:Glow | — | Glow. |
| softEdge | number | — | Soft edges (a:softEdge), radius in reference pixels at a 720-pixel short edge. |
| reflection | ref:Reflection | — | Reflection. |
| blur | number | — | Blur of the whole shape (a:blur), radius in reference pixels at a 720-pixel short edge. |
| rotate | number | — | Rotation in degrees, clockwise, about the shape's center (a:xfrm rot). Its connection sites turn with it. |
| flip | enum | — | Mirror the geometry (a:xfrm flipH, flipV). The text is not mirrored.
|
| text | ref:ContentPayload/properties/text | — | Text inside the shape's text rectangle (a string or TextRun[]), fitted by OPF's measured fonts from the body size down to the readability floor and never below it. |
| anchor | enum | — | Vertical placement of the text in the text rectangle (a:bodyPr anchor). Default middle.
|
| padding | ref:ShapePadding | — | Text insets inside the text rectangle. |
| textDirection | enum | — | Text direction (a:bodyPr vert). Default horizontal.
|
| alt | string | — | Alternative text (p:cNvPr descr). Without it the shape's text is what is read. |
| decorative | boolean | — | Mark the shape decorative (a16:decorative): screen readers skip it. |
| hidden | boolean | — | Keep the shape in the file but do not draw it (p:cNvPr hidden). A link on a hidden shape is a validation finding (opf/shape-link-hidden). |
| link | string | — | URL opened when the shape is clicked in a slide show (a:hlinkClick): an http(s) URL, a 'mailto:' address or a 'tel:' number. |
| extensions | object | — | Custom data passthrough for agent workflows; ignored by the engine but preserved across read/write round-trips. |
id
typestringrequirednodefault—
Optional stable identifier, unique among slide, payload and overlay ids in the document. A connector names it in 'from' or 'to'.
{
"id": "badge-new"
}x
typeref:FiniteNumberrequirednodefault—
The shape's start edge as a signed fraction of the slide width, measured from the slide's start edge: the left edge in a left-to-right deck, the right edge in a right-to-left one. A shape sits over the layout, and the layout mirrors, so this coordinate is logical; only the position mirrors, never the geometry (an arrow keeps the way it points). Negative values or values greater than 1 place the shape partly or wholly outside the slide. With 'y', 'width' and 'height'.
y
typeref:FiniteNumberrequirednodefault—
Top edge as a signed fraction of the slide height, from the top edge. Negative values or values greater than 1 place the shape partly or wholly outside the slide.
width
typenumberrequirednodefault—
Width as a fraction of the slide width, from 0 (a vertical line) up to 8. Above 1 the shape is wider than the slide, for a circle or band that bleeds off it; the slide crops what lies outside.
height
typenumberrequirednodefault—
Height as a fraction of the slide height, from 0 (a horizontal line) up to 8. Above 1 the shape is taller than the slide.
at
typeref:OverlayAnchorrequirednodefault—
at.edge· Allowed values"top""bottom""start""end""center"
layer
typeenumrequirednodefault—
Overlay shapes only. front (the default) draws the shape over the slide: above the content and the furniture. back draws it behind the slide: above the background and the watermark, below the content and the furniture (a panel or band behind a block). Array order stacks the shapes within each layer. Connectors are always in front.
layer· Allowed values"front""back"
{
"layer": "front"
}connector
typeref:Connectorrequirednodefault—
Makes the entry a connector: what it joins and how it runs.
connector.route· Allowed values"straight""elbow""curved"
shape
typeref:ShapePresetrequirednodefault—
The preset geometry, as on a shape block. Default rect.
shape· Allowed values"line", "lineInv", "triangle", "rtTriangle", "rect", "diamond", "parallelogram", "trapezoid", "nonIsoscelesTrapezoid", "pentagon", "hexagon", "heptagon", "octagon", "decagon", "dodecagon", "star4", "star5", "star6", "star7", "star8", "star10", "star12", "star16", "star24", "star32", "roundRect", "round1Rect", "round2SameRect", "round2DiagRect", "snipRoundRect", "snip1Rect", "snip2SameRect", "snip2DiagRect", "plaque", "ellipse", "teardrop", "homePlate", "chevron", "pieWedge", "pie", "blockArc", "donut", "noSmoking", "rightArrow", "leftArrow", "upArrow", "downArrow", "stripedRightArrow", "notchedRightArrow", "bentUpArrow", "leftRightArrow", "upDownArrow", "leftUpArrow", "leftRightUpArrow", "quadArrow", "leftArrowCallout", "rightArrowCallout", "upArrowCallout", "downArrowCallout", "leftRightArrowCallout", "upDownArrowCallout", "quadArrowCallout", "bentArrow", "uturnArrow", "circularArrow", "leftCircularArrow", "leftRightCircularArrow", "curvedRightArrow", "curvedLeftArrow", "curvedUpArrow", "curvedDownArrow", "swooshArrow", "cube", "can", "lightningBolt", "heart", "sun", "moon", "smileyFace", "irregularSeal1", "irregularSeal2", "foldedCorner", "bevel", "frame", "halfFrame", "corner", "diagStripe", "chord", "arc", "leftBracket", "rightBracket", "leftBrace", "rightBrace", "bracketPair", "bracePair", "straightConnector1", "bentConnector2", "bentConnector3", "bentConnector4", "bentConnector5", "curvedConnector2", "curvedConnector3", "curvedConnector4", "curvedConnector5", "callout1", "callout2", "callout3", "accentCallout1", "accentCallout2", "accentCallout3", "borderCallout1", "borderCallout2", "borderCallout3", "accentBorderCallout1", "accentBorderCallout2", "accentBorderCallout3", "wedgeRectCallout", "wedgeRoundRectCallout", "wedgeEllipseCallout", "cloudCallout", "cloud", "ribbon", "ribbon2", "ellipseRibbon", "ellipseRibbon2", "leftRightRibbon", "verticalScroll", "horizontalScroll", "wave", "doubleWave", "plus", "flowChartProcess", "flowChartDecision", "flowChartInputOutput", "flowChartPredefinedProcess", "flowChartInternalStorage", "flowChartDocument", "flowChartMultidocument", "flowChartTerminator", "flowChartPreparation", "flowChartManualInput", "flowChartManualOperation", "flowChartConnector", "flowChartPunchedCard", "flowChartPunchedTape", "flowChartSummingJunction", "flowChartOr", "flowChartCollate", "flowChartSort", "flowChartExtract", "flowChartMerge", "flowChartOfflineStorage", "flowChartOnlineStorage", "flowChartMagneticTape", "flowChartMagneticDisk", "flowChartMagneticDrum", "flowChartDisplay", "flowChartDelay", "flowChartAlternateProcess", "flowChartOffpageConnector", "actionButtonBlank", "actionButtonHome", "actionButtonHelp", "actionButtonInformation", "actionButtonForwardNext", "actionButtonBackPrevious", "actionButtonEnd", "actionButtonBeginning", "actionButtonReturn", "actionButtonDocument", "actionButtonSound", "actionButtonMovie", "gear6", "gear9", "funnel", "mathPlus", "mathMinus", "mathMultiply", "mathDivide", "mathEqual", "mathNotEqual", "cornerTabs", "squareTabs", "plaqueTabs", "chartX", "chartStar", "chartPlus"
{
"shape": "line"
}path
typeref:ShapePathrequirednodefault—
Custom geometry instead of a preset (a:custGeom), as on a shape block.
adjust
typeobjectrequirednodefault—
The preset's adjust handles (a:avLst) in OPF units, as on a shape block. On a connector, the adjust values of its connector preset (adj1 of an elbow or a curve between sites on one axis, a fraction of the frame's width), which replace the automatic route's, so a route made in PowerPoint is kept exactly.
{
"adjust": {
"adj": 0.25
}
}fill
typeref:ShapeFillrequirednodefault—
'none', a ColorRef, { gradient } or { pattern }. Default the style's fill.
fill· Named choices"none", "accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"fill (anyOf 2) (anyOf 4).color,fill (anyOf 3).gradient.stops[].color,fill (anyOf 4).pattern.foregroundColor,fill (anyOf 4).pattern.backgroundColor· Named choices"accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"fill (anyOf 3).gradient.type· Allowed values"linear", "radial", "rectangle", "shape"
opacity
typenumberrequirednodefault—
The fill's opacity (a:alpha). Default 1.
stroke
typeref:Strokerequirednodefault—
A shape's line along its outline (default the style's line), or a connector's line: color, width, dash, compound, sketch and arrowheads ('start' at 'from', 'end' at 'to'; default a 2-pixel line in the slide's text color with no arrowheads).
stroke· Named choices"none"stroke (anyOf 2).color,stroke (anyOf 2).color (anyOf 4).color,stroke (anyOf 2).gradient.stops[].color· Named choices"accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"stroke (anyOf 2).gradient.type· Allowed values"linear", "radial", "rectangle", "shape"stroke (anyOf 2).dash· Named choices"solid", "dot", "dash", "longDash", "dashDot", "longDashDot", "longDashDotDot", "sysDot", "sysDash", "sysDashDot", "sysDashDotDot"stroke (anyOf 2).cap· Allowed values"flat", "round", "square"stroke (anyOf 2).join· Allowed values"miter", "round", "bevel"stroke (anyOf 2).compound· Allowed values"single", "double", "thickThin", "thinThick", "triple"stroke (anyOf 2).align· Allowed values"center", "inside"stroke (anyOf 2).start.type· Allowed values"none", "triangle", "stealth", "diamond", "oval", "arrow"stroke (anyOf 2).start.width,stroke (anyOf 2).start.length· Allowed values"small", "medium", "large"stroke (anyOf 2).sketch· Allowed values"curved", "freehand", "scribble"
style
typeenumrequirednodefault—
The theme shape style, as on a shape block. Default moderate.
style· Allowed values"none""subtle""moderate""intense"
{
"style": "none"
}shadow
typeref:Shadowrequirednodefault—
Outer shadow.
shadow· Named choices"soft", "hard", "perspective"shadow (anyOf 2).color,shadow (anyOf 2).color (anyOf 4).color· Named choices"accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"
innerShadow
typeref:InnerShadowrequirednodefault—
Inner shadow.
innerShadow.color,innerShadow.color (anyOf 4).color· Named choices"accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"
glow
typeref:Glowrequirednodefault—
Glow.
glow.color,glow.color (anyOf 4).color· Named choices"accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"
softEdge
typenumberrequirednodefault—
Soft edges (a:softEdge), radius in reference pixels at a 720-pixel short edge.
reflection
typeref:Reflectionrequirednodefault—
Reflection.
blur
typenumberrequirednodefault—
Blur of the whole shape (a:blur), radius in reference pixels at a 720-pixel short edge.
rotate
typenumberrequirednodefault—
Rotation in degrees, clockwise, about the shape's center (a:xfrm rot). Its connection sites turn with it.
flip
typeenumrequirednodefault—
Mirror the geometry (a:xfrm flipH, flipV). The text is not mirrored.
flip· Allowed values"horizontal""vertical""both"
{
"flip": "horizontal"
}text
typeref:ContentPayload/properties/textrequirednodefault—
Text inside the shape's text rectangle (a string or TextRun[]), fitted by OPF's measured fonts from the body size down to the readability floor and never below it.
text (oneOf 2)[] (oneOf 2).color (anyOf 2).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"
anchor
typeenumrequirednodefault—
Vertical placement of the text in the text rectangle (a:bodyPr anchor). Default middle.
anchor· Allowed values"top""middle""bottom"
{
"anchor": "top"
}padding
typeref:ShapePaddingrequirednodefault—
Text insets inside the text rectangle.
textDirection
typeenumrequirednodefault—
Text direction (a:bodyPr vert). Default horizontal.
textDirection· Allowed values"horizontal""vertical""vertical270""stacked"
{
"textDirection": "horizontal"
}alt
typestringrequirednodefault—
Alternative text (p:cNvPr descr). Without it the shape's text is what is read.
decorative
typebooleanrequirednodefault—
Mark the shape decorative (a16:decorative): screen readers skip it.
link
typestringrequirednodefault—pattern^(https?://|mailto:|tel:)\S+$
URL opened when the shape is clicked in a slide show (a:hlinkClick): an http(s) URL, a 'mailto:' address or a 'tel:' number.
{
"link": "https://acme.com/pricing"
}extensions
typeobjectrequirednodefault—
Custom data passthrough for agent workflows; ignored by the engine but preserved across read/write round-trips.
Complete definition constraints
{
"type": "object",
"additionalProperties": false,
"description": "An entry of slide 'shapes', drawn over the composed slide above the content and the furniture, later entries on top; it never moves content. An entry with 'connector' is a connector between two blocks or overlay shapes: it takes only 'id', 'connector', 'adjust', 'stroke', 'alt', 'decorative', 'hidden' and 'extensions'; core routes it as PowerPoint's own connector presets and PPTX export writes a native p:cxnSp glued to the shapes at its ends, so it follows them when they are moved in PowerPoint. Any other entry is an overlay shape: the shape block vocabulary (geometry, paint, effects, transform, text, accessibility) and exactly one placement, 'x', 'y', 'width' and 'height' (fractions of the slide) or 'at' (against a block, so it follows the block wherever composition puts it); PPTX export writes a native p:sp.",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"description": "Optional stable identifier, unique among slide, payload and overlay ids in the document. A connector names it in 'from' or 'to'.",
"examples": [
"badge-new",
"callout-1"
]
},
"x": {
"$ref": "#/$defs/FiniteNumber",
"description": "The shape's start edge as a signed fraction of the slide width, measured from the slide's start edge: the left edge in a left-to-right deck, the right edge in a right-to-left one. A shape sits over the layout, and the layout mirrors, so this coordinate is logical; only the position mirrors, never the geometry (an arrow keeps the way it points). Negative values or values greater than 1 place the shape partly or wholly outside the slide. With 'y', 'width' and 'height'."
},
"y": {
"$ref": "#/$defs/FiniteNumber",
"description": "Top edge as a signed fraction of the slide height, from the top edge. Negative values or values greater than 1 place the shape partly or wholly outside the slide."
},
"width": {
"type": "number",
"minimum": 0,
"maximum": 8,
"description": "Width as a fraction of the slide width, from 0 (a vertical line) up to 8. Above 1 the shape is wider than the slide, for a circle or band that bleeds off it; the slide crops what lies outside."
},
"height": {
"type": "number",
"minimum": 0,
"maximum": 8,
"description": "Height as a fraction of the slide height, from 0 (a horizontal line) up to 8. Above 1 the shape is taller than the slide."
},
"at": {
"$ref": "#/$defs/OverlayAnchor"
},
"layer": {
"type": "string",
"enum": [
"front",
"back"
],
"description": "Overlay shapes only. front (the default) draws the shape over the slide: above the content and the furniture. back draws it behind the slide: above the background and the watermark, below the content and the furniture (a panel or band behind a block). Array order stacks the shapes within each layer. Connectors are always in front."
},
"connector": {
"$ref": "#/$defs/Connector",
"description": "Makes the entry a connector: what it joins and how it runs."
},
"shape": {
"$ref": "#/$defs/ShapePreset",
"description": "The preset geometry, as on a shape block. Default rect."
},
"path": {
"$ref": "#/$defs/ShapePath",
"description": "Custom geometry instead of a preset (a:custGeom), as on a shape block."
},
"adjust": {
"type": "object",
"propertyNames": {
"pattern": "^[a-z][A-Za-z0-9]*$"
},
"additionalProperties": {
"type": "number"
},
"description": "The preset's adjust handles (a:avLst) in OPF units, as on a shape block. On a connector, the adjust values of its connector preset (adj1 of an elbow or a curve between sites on one axis, a fraction of the frame's width), which replace the automatic route's, so a route made in PowerPoint is kept exactly.",
"examples": [
{
"adj": 0.25
}
]
},
"fill": {
"$ref": "#/$defs/ShapeFill",
"description": "'none', a ColorRef, { gradient } or { pattern }. Default the style's fill."
},
"opacity": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "The fill's opacity (a:alpha). Default 1."
},
"stroke": {
"$ref": "#/$defs/Stroke",
"description": "A shape's line along its outline (default the style's line), or a connector's line: color, width, dash, compound, sketch and arrowheads ('start' at 'from', 'end' at 'to'; default a 2-pixel line in the slide's text color with no arrowheads)."
},
"style": {
"type": "string",
"enum": [
"none",
"subtle",
"moderate",
"intense"
],
"description": "The theme shape style, as on a shape block. Default moderate."
},
"shadow": {
"$ref": "#/$defs/Shadow",
"description": "Outer shadow."
},
"innerShadow": {
"$ref": "#/$defs/InnerShadow",
"description": "Inner shadow."
},
"glow": {
"$ref": "#/$defs/Glow",
"description": "Glow."
},
"softEdge": {
"type": "number",
"minimum": 0,
"maximum": 200,
"description": "Soft edges (a:softEdge), radius in reference pixels at a 720-pixel short edge."
},
"reflection": {
"$ref": "#/$defs/Reflection",
"description": "Reflection."
},
"blur": {
"type": "number",
"minimum": 0,
"maximum": 200,
"description": "Blur of the whole shape (a:blur), radius in reference pixels at a 720-pixel short edge."
},
"rotate": {
"type": "number",
"minimum": -360,
"maximum": 360,
"description": "Rotation in degrees, clockwise, about the shape's center (a:xfrm rot). Its connection sites turn with it."
},
"flip": {
"type": "string",
"enum": [
"horizontal",
"vertical",
"both"
],
"description": "Mirror the geometry (a:xfrm flipH, flipV). The text is not mirrored."
},
"text": {
"$ref": "#/$defs/ContentPayload/properties/text",
"description": "Text inside the shape's text rectangle (a string or TextRun[]), fitted by OPF's measured fonts from the body size down to the readability floor and never below it."
},
"anchor": {
"type": "string",
"enum": [
"top",
"middle",
"bottom"
],
"description": "Vertical placement of the text in the text rectangle (a:bodyPr anchor). Default middle."
},
"padding": {
"$ref": "#/$defs/ShapePadding",
"description": "Text insets inside the text rectangle."
},
"textDirection": {
"type": "string",
"enum": [
"horizontal",
"vertical",
"vertical270",
"stacked"
],
"description": "Text direction (a:bodyPr vert). Default horizontal."
},
"alt": {
"type": "string",
"description": "Alternative text (p:cNvPr descr). Without it the shape's text is what is read."
},
"decorative": {
"type": "boolean",
"description": "Mark the shape decorative (a16:decorative): screen readers skip it."
},
"hidden": {
"type": "boolean",
"description": "Keep the shape in the file but do not draw it (p:cNvPr hidden). A link on a hidden shape is a validation finding (opf/shape-link-hidden)."
},
"link": {
"type": "string",
"pattern": "^(https?://|mailto:|tel:)\\S+$",
"description": "URL opened when the shape is clicked in a slide show (a:hlinkClick): an http(s) URL, a 'mailto:' address or a 'tel:' number.",
"examples": [
"https://acme.com/pricing"
]
},
"extensions": {
"type": "object",
"description": "Custom data passthrough for agent workflows; ignored by the engine but preserved across read/write round-trips."
}
},
"examples": [
{
"shape": "wedgeRectCallout",
"text": "New this quarter",
"x": 0.62,
"y": 0.12,
"width": 0.25,
"height": 0.12,
"style": "subtle"
},
{
"id": "badge",
"shape": "ellipse",
"text": "3",
"at": {
"block": "team-photo",
"edge": "top",
"offset": -12
}
},
{
"connector": {
"from": "plan",
"to": "build",
"route": "elbow"
},
"stroke": {
"width": 2,
"end": {
"type": "triangle"
}
}
}
]
}