/schemas/help/pptx/diagram.json

{
  "$schema": "../_schema.json",
  "format": "pptx",
  "element": "diagram",
  "elementAliases": ["flowchart"],
  "parent": "slide",
  "operations": {
    "add": true,
    "set": false,
    "get": false,
    "query": false,
    "remove": false
  },
  "paths": {
    "positional": [
      "/slide[N]"
    ]
  },
  "note": "Renders a mermaid diagram into native, editable shapes + connectors on the slide. Aliases: flowchart. ADD-ONLY synthesizer (like 'equation'): there is no persistent 'diagram' node, but the whole diagram is wrapped in ONE group and Add returns its path (/slide[N]/group[K]), so it stays adjustable as a unit. get /slide[N]/group[K] reads it back (x/y/width/height); set /slide[N]/group[K] --prop width=… --prop height=… moves or resizes the whole diagram — child font sizes re-bake with the resize so text stays proportional; and remove /slide[N]/group[K] deletes it. Give ONE of width/height to scale proportionally (aspect preserved), or BOTH for an exact box. A human can also drag the single group object. The mermaid header selects the layout engine; supported: flowchart / graph, sequenceDiagram. Other mermaid types (gantt, pie, classDiagram, stateDiagram, erDiagram, ...) are rejected with a clear message until implemented. SIZING: by default the diagram is scaled to FIT the current slide (the slide size is never changed) and centred; give x/y/width/height to place it in an explicit box (like picture/chart). Pass poster=true to instead grow the slide to the whole diagram (export-a-diagram model). Aspect ratio is always preserved.",
  "properties": {
    "mermaid": {
      "type": "string",
      "description": "Mermaid diagram source. Canonical (mirrors equation's 'formula'). Aliases: text, dsl. The first line's header (flowchart TD / sequenceDiagram / ...) selects the diagram kind.",
      "aliases": ["text", "dsl"],
      "add": true,
      "set": false,
      "get": false,
      "examples": [
        "--prop mermaid=\"flowchart TD; A[Start] --> B{OK?} --> C[Done]\"",
        "--prop text=\"sequenceDiagram; A->>B: hi; B-->>A: ok\""
      ],
      "enforcement": "report"
    },
    "src": {
      "type": "string",
      "description": "Path to a .mmd file to load the mermaid source from (used when no inline mermaid/text/dsl is given). Consistent with picture/media 'src' = a file path. Alias: path.",
      "aliases": ["path"],
      "add": true,
      "set": false,
      "get": false,
      "examples": [
        "--prop src=diagram.mmd"
      ],
      "enforcement": "report"
    },
    "x": {
      "type": "length",
      "description": "Top-left X of the diagram's box (cm/in/pt/EMU). Default: centred horizontally on the slide. The slide size is never changed (use poster=true for that).",
      "add": true,
      "set": false,
      "get": false,
      "examples": [
        "--prop x=2cm"
      ],
      "enforcement": "report"
    },
    "y": {
      "type": "length",
      "description": "Top-left Y of the diagram's box (cm/in/pt/EMU). Default: centred vertically on the slide.",
      "add": true,
      "set": false,
      "get": false,
      "examples": [
        "--prop y=2cm"
      ],
      "enforcement": "report"
    },
    "width": {
      "type": "length",
      "description": "Width of the box the diagram is scaled to fit (cm/in/pt/EMU). Aspect ratio is preserved (may letterbox against height). Default: the slide content width. Mirrors picture/chart 'width'.",
      "add": true,
      "set": false,
      "get": false,
      "examples": [
        "--prop width=15cm"
      ],
      "enforcement": "report"
    },
    "height": {
      "type": "length",
      "description": "Height of the box the diagram is scaled to fit (cm/in/pt/EMU). Aspect ratio is preserved. Default: the slide content height.",
      "add": true,
      "set": false,
      "get": false,
      "examples": [
        "--prop height=10cm"
      ],
      "enforcement": "report"
    },
    "poster": {
      "type": "boolean",
      "description": "When true, grow the SLIDE to the diagram's natural size instead of fitting the diagram into the slide (export-a-diagram-as-a-slide model). Ignores x/y/width/height. Default false — the slide size is preserved.",
      "add": true,
      "set": false,
      "get": false,
      "examples": [
        "--prop poster=true"
      ],
      "enforcement": "report"
    },
    "render": {
      "type": "string",
      "description": "How to render. auto (default): use real mermaid.js via a headless browser (Chrome/Chromium/Edge) when available — covers EVERY mermaid type (gantt/pie/class/state/er/…) at full fidelity, embedded as a PNG with the mermaid source stamped into alt-text (regenerable); falls back to the native synthesizer when no browser is present. native: always the built-in editable-shape synthesizer (no browser; supported subset only; fully editable in PowerPoint). image: force the browser path (errors if no browser). mermaid.js is fetched once to a local cache (mirror d.officecli.ai, CDN fallback).",
      "enum": ["auto", "native", "image"],
      "add": true,
      "set": false,
      "get": false,
      "examples": [
        "--prop render=native",
        "--prop render=image"
      ],
      "enforcement": "report"
    }
  }
}