iofficeai--officecli/schemas/help/pptx/slide.json

{
  "$schema": "../_schema.json",
  "format": "pptx",
  "element": "slide",
  "parent": "presentation",
  "operations": {
    "add": true,
    "set": true,
    "get": true,
    "query": true,
    "remove": true
  },
  "paths": {
    "positional": ["/slide[N]"]
  },
  "note": "Layouts are resolved by name (ResolveSlideLayout). 'title'/'text' shorthand inserts title/content text shapes at Add. Transition `morph…` auto-prefixes shape names. Newly added slides have no placeholders — populate via title/text shorthand, `--type placeholder --prop phType=title`, or `--type shape|textbox`.",
  "properties": {
    "layout": {
      "type": "string",
      "description": "slide layout name (e.g. 'Title Slide', 'Title and Content'). Resolved against the presentation's slide masters. The `layout` property is metadata only — placeholder slots defined in the layout are NOT auto-materialized on the slide. To populate slots: pass `--prop title=…` to auto-emit a title placeholder shape (phType=title); pass `--prop text=…` to auto-emit a body placeholder shape (phType=body); or add placeholders explicitly with `--type placeholder --prop phType=<role>`.",
      "add": true, "set": true, "get": true,
      "examples": ["--prop layout=\"Title Slide\""],
      "readback": "layout name string",
      "enforcement": "report"
    },
    "title": {
      "type": "string",
      "description": "title text. Creates a Title shape at Add time, carrying <p:ph type=\"title\"/>. To modify or read the title text after creation, target the title shape directly (e.g. /slide[N]/shape[@phType=title]).",
      "add": true, "set": false, "get": false,
      "examples": ["--prop title=\"Introduction\""],
      "readback": "not surfaced at slide level; descend into the title shape",
      "enforcement": "report"
    },
    "text": {
      "type": "string",
      "description": "content body text. Creates a Content text shape at Add time, carrying <p:ph type=\"body\" idx=\"1\"/> so it binds to the layout's body slot.",
      "add": true, "set": false, "get": false,
      "examples": ["--prop text=\"Body text\""],
      "readback": "not surfaced at slide level",
      "enforcement": "report"
    },
    "background": {
      "type": "color",
      "description": "slide background. Accepts: hex color (`#RGB`, `#RRGGBB`, `#RRGGBBAA` for solid+alpha), scheme color (`accent1`..`accent6`, `dark1`, `dark2`, `light1`, `light2`, `hyperlink`, `followedHyperlink`), `transparent` (or `none`/`clear`), linear gradient `C1-C2[-C3][-angle]` (angle in degrees, also accepts `LINEAR;C1;C2[;angle]`), radial gradient `radial:C1-C2[-focus]` (focus: `tl`/`tr`/`bl`/`br`/`center`), path gradient `path:C1-C2[-focus]`, and image fill `image:/path/to/file` (local path; pair with `background.mode`/`background.alpha`/`background.scale`).",
      "add": true, "set": true, "get": true,
      "examples": ["--prop background=#FFFFFF"],
      "readback": "resolved background descriptor",
      "enforcement": "report"
    },
    "transition": {
      "type": "string",
      "description": "transition name (fade, push, wipe, morph, etc.). 'morph...' triggers auto-prefixing of shape names.",
      "add": true, "set": true, "get": true,
      "examples": ["--prop transition=fade"],
      "readback": "transition name",
      "enforcement": "report"
    },
    "advanceTime": {
      "type": "number",
      "description": "auto-advance time in milliseconds (integer). e.g. 5000 = 5 seconds.",
      "aliases": ["advancetime"],
      "add": true, "set": true, "get": true,
      "examples": ["--prop advanceTime=5000"],
      "readback": "milliseconds (integer)",
      "enforcement": "report"
    },
    "advanceClick": {
      "type": "bool",
      "description": "advance on click.",
      "aliases": ["advanceclick"],
      "add": true, "set": true, "get": true,
      "examples": ["--prop advanceClick=true"],
      "readback": "true/false",
      "enforcement": "report"
    },
    "notes": {
      "type": "string",
      "description": "slide notes text. Set-only at creation time.",
      "add": false, "set": true, "get": true,
      "examples": ["--prop notes=\"Speaker notes here\""],
      "readback": "notes text when present",
      "enforcement": "report"
    },
    "hidden": {
      "type": "bool",
      "description": "true when the slide is hidden from slideshow (Slide/@show=false).",
      "add": true, "set": true, "get": true,
      "readback": "true if slide is hidden in slideshow",
      "enforcement": "report"
    },
    "layoutType": {
      "type": "string",
      "description": "slide layout type name as encoded on the underlying SlideLayout (e.g. blank, title, titleOnly, twoContent, obj, txAndObj). Distinct from `layout`, which is the user-facing layout display name.",
      "add": false, "set": false, "get": true,
      "readback": "layout type token from SlideLayout/@type",
      "enforcement": "report"
    },
    "background.alpha":  { "type":"number", "add":false, "set":true,  "get":true, "description":"slide background fill alpha as percent (0..100). Settable on existing solid or image backgrounds: on solid, rewrites the color with the given alpha (equivalent to `background=RRGGBBAA`); on image, emits `<a:alphaModFix/>`. Surfaces on get when the resolved fill carries an alpha channel.", "readback":"integer percent 0..100", "enforcement":"report" },
    "background.crop":   { "type":"string", "add":false, "set":false, "get":true, "description":"slide background image crop quad in `l,t,r,b` percent units (CT_RelativeRect).", "readback":"comma-separated `l,t,r,b` quad", "enforcement":"report" },
    "background.mode":   { "type":"string", "add":false, "set":true,  "get":true, "description":"slide background image fill mode — `stretch` (default), `tile`, or `center`. Settable on an existing image background; emitted on get only when non-default.", "readback":"`tile` | `center`", "enforcement":"report" },
    "background.ref":    { "type":"number", "add":false, "set":false, "get":true, "description":"theme background reference index — bgRef/@idx (1001/1002/1003 etc.) when the slide inherits from the theme.", "readback":"integer theme bg ref id", "enforcement":"report" },
    "background.scale":  { "type":"number", "add":false, "set":true,  "get":true, "description":"tile-fill scale percent (sx, both axes), 1..500. Settable on an existing image background with background.mode=tile; surfaces on get with background.mode=tile.", "readback":"integer percent", "enforcement":"report" },
    "matchedShapes":     { "type":"number", "add":false, "set":false, "get":true, "description":"morph transition: number of shapes from the previous slide that matched on the current slide.", "readback":"integer match count", "enforcement":"report" },
    "morphMode":         { "type":"string", "add":false, "set":false, "get":true, "description":"morph transition mode (byObject default, or other p:morph @option token).", "readback":"morph mode token", "enforcement":"report" },
    "morphShapes":       { "type":"number", "add":false, "set":false, "get":true, "description":"morph transition: number of candidate shapes considered for matching on this slide.", "readback":"integer candidate count", "enforcement":"report" }
  },
  "children": [
    { "element": "shape",       "pathSegment": "shape",       "cardinality": "0..n" },
    { "element": "table",       "pathSegment": "table",       "cardinality": "0..n" },
    { "element": "chart",       "pathSegment": "chart",       "cardinality": "0..n" },
    { "element": "picture",     "pathSegment": "picture",     "cardinality": "0..n" },
    { "element": "placeholder", "pathSegment": "placeholder", "cardinality": "0..n" }
  ]
}