OPF

Search docs

Loading documentation…
    OpenPresentation/opf
    Browse docs
    On this page
    View source

    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

    Definition
    #/$defs/OverlayShape
    Form
    object
    Source
    spec/schemas/opf.schema.json

    Field index

    FieldTypeReq.Description
    idstring—Optional stable identifier, unique among slide, payload and overlay ids in the document. A connector names it in 'from' or 'to'.
    xref: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'.
    yref: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.
    widthnumber—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.
    heightnumber—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.
    atref:OverlayAnchor—
    layerenum—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"
    connectorref:Connector—Makes the entry a connector: what it joins and how it runs.
    shaperef:ShapePreset—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"
    pathref:ShapePath—Custom geometry instead of a preset (a:custGeom), as on a shape block.
    adjustobject—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.
    fillref:ShapeFill—'none', a ColorRef, { gradient } or { pattern }. Default the style's fill.
    fill · Named choices (see schema for other values and constraints)
    "none""accent1""accent2""accent3""accent4""accent5""accent6""dark1""dark2""light1""light2""hyperlink""followedHyperlink""primary""secondary""accent""background""surface""surfaceAlt""text""textSecondary"
    opacitynumber—The fill's opacity (a:alpha). Default 1.
    strokeref: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).
    stroke · Named choices (see schema for other values and constraints)
    "none"
    styleenum—The theme shape style, as on a shape block. Default moderate.
    style · Allowed values
    "none""subtle""moderate""intense"
    shadowref:Shadow—Outer shadow.
    shadow · Named choices (see schema for other values and constraints)
    "soft""hard""perspective"
    innerShadowref:InnerShadow—Inner shadow.
    glowref:Glow—Glow.
    softEdgenumber—Soft edges (a:softEdge), radius in reference pixels at a 720-pixel short edge.
    reflectionref:Reflection—Reflection.
    blurnumber—Blur of the whole shape (a:blur), radius in reference pixels at a 720-pixel short edge.
    rotatenumber—Rotation in degrees, clockwise, about the shape's center (a:xfrm rot). Its connection sites turn with it.
    flipenum—Mirror the geometry (a:xfrm flipH, flipV). The text is not mirrored.
    flip · Allowed values
    "horizontal""vertical""both"
    textref: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.
    anchorenum—Vertical placement of the text in the text rectangle (a:bodyPr anchor). Default middle.
    anchor · Allowed values
    "top""middle""bottom"
    paddingref:ShapePadding—Text insets inside the text rectangle.
    textDirectionenum—Text direction (a:bodyPr vert). Default horizontal.
    textDirection · Allowed values
    "horizontal""vertical""vertical270""stacked"
    altstring—Alternative text (p:cNvPr descr). Without it the shape's text is what is read.
    decorativeboolean—Mark the shape decorative (a16:decorative): screen readers skip it.
    hiddenboolean—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).
    linkstring—URL opened when the shape is clicked in a slide show (a:hlinkClick): an http(s) URL, a 'mailto:' address or a 'tel:' number.
    extensionsobject—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.json
    {
      "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.json
    {
      "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.json
    {
      "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.json
    {
      "adjust": {
        "adj": 0.25
      }
    }

    fill

    typeref:ShapeFillrequirednodefault—

    'none', a ColorRef, { gradient } or { pattern }. Default the style's fill.

    Named choices are not exhaustive. See the schema for other values and constraints.
    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).

    Named choices are not exhaustive. See the schema for other values and constraints.
    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.json
    {
      "style": "none"
    }

    shadow

    typeref:Shadowrequirednodefault—

    Outer shadow.

    Named choices are not exhaustive. See the schema for other values and constraints.
    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.

    Named choices are not exhaustive. See the schema for other values and constraints.
    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.

    Named choices are not exhaustive. See the schema for other values and constraints.
    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.json
    {
      "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.json
    {
      "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.json
    {
      "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.

    hidden

    typebooleanrequirednodefault—

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

    extensions

    typeobjectrequirednodefault—

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

    Complete definition constraints
    Schema 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"
            }
          }
        }
      ]
    }