iofficeai--officecli/schemas/help/docx/diagram.json

{
  "$schema": "../_schema.json",
  "format": "docx",
  "element": "diagram",
  "elementAliases": ["flowchart"],
  "parent": "body",
  "operations": {
    "add": true,
    "set": false,
    "get": false,
    "query": false,
    "remove": false
  },
  "paths": {
    "positional": [
      "/body"
    ]
  },
  "note": "Renders a mermaid diagram into native, editable drawing shapes + connectors in the body. Aliases: flowchart. ADD-ONLY synthesizer (like 'equation'): there is no persistent 'diagram' node, but the whole diagram is wrapped in ONE group (wpg:wgp) and Add returns its path (/body/group[N]), so it stays adjustable as a unit. get /body/group[N] reads the group back (type=group with x/y/width/height); set /body/group[N] --prop width=… --prop height=… resizes the whole diagram — child font sizes re-bake with the resize so text stays proportional; give ONE of width/height to scale proportionally (aspect preserved), or BOTH for an exact box. set /body/group[N] --prop x=… --prop y=… moves the whole diagram (rewrites the floating anchor offset; a single axis leaves the other in place). remove /body/group[N] deletes it (the group and every child, no husk). Non-positive sizes are rejected. A human can instead drag the single group object in Word (note: an interactive drag scales the geometry but Word does not re-bake the absolute font size — use the CLI set for text to scale too). Individual node text is still reachable at /body/textbox[K]. (docx has no drawing 'query' — address the group by index.) 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: docx has no slide to resize (no pptx-style poster) — the diagram always scales into the available space. Give width/height for an explicit box (may enlarge, aspect ratio preserved, like picture/chart); with neither it fits the section's text-area width and is never enlarged. Placed as floating shapes anchored to the page margin. The parse + layout engine is shared with the pptx 'diagram' emitter; only the docx drawing output differs.",
  "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 'src' = a file path. Alias: path.",
      "aliases": ["path"],
      "add": true,
      "set": false,
      "get": false,
      "examples": [
        "--prop src=diagram.mmd"
      ],
      "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 enlarge past the text width. Default: the section text-area width (shrink-only). Mirrors picture/chart 'width'.",
      "add": true,
      "set": false,
      "get": false,
      "examples": [
        "--prop width=12cm"
      ],
      "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: unbounded (width governs).",
      "add": true,
      "set": false,
      "get": false,
      "examples": [
        "--prop height=8cm"
      ],
      "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 Word). 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"
    }
  }
}