Raw schema
{
"type": "object",
"properties": {
"prompt": {
"type": [
"string",
"null"
],
"maxLength": 8000,
"description": "Natural language description of the diagram to generate. When provided, the server uses AI to convert this into a structured diagram spec. Max 8000 characters. Example: \"flowchart showing user login with validation and error handling\""
},
"type": {
"type": [
"string",
"null"
],
"enum": [
"flowchart",
"mindmap",
"block-diagram",
"matrix",
"timeline",
"gantt",
"er-diagram",
"sequence",
"process-flow",
"pyramid",
"funnel",
"radar",
"fishbone"
],
"description": "Diagram type. Required when providing structured nodes/edges, optional with prompt."
},
"sections": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
]
},
"title": {
"type": "string"
},
"subtitle": {
"type": [
"string",
"null"
]
},
"items": {
"type": "array",
"items": {
"type": "string"
}
},
"icons": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
},
"itemIds": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
},
"itemShapes": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
},
"itemBackgroundColors": {
"type": [
"array",
"null"
],
"items": {
"type": "string",
"maxLength": 40
}
},
"itemHeatIntensities": {
"type": [
"array",
"null"
],
"items": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"sectionBackgroundColor": {
"type": [
"string",
"null"
],
"maxLength": 40
},
"sectionHeatIntensity": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 1
},
"row": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"col": {
"type": [
"integer",
"null"
],
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"id",
"title",
"subtitle",
"items",
"icons",
"itemIds",
"itemShapes",
"itemBackgroundColors",
"itemHeatIntensities",
"sectionBackgroundColor",
"sectionHeatIntensity",
"row",
"col"
]
},
"description": "Matrix sections. Each section has a title, optional subtitle, and items. Used with type=\"matrix\"."
},
"title": {
"type": [
"string",
"null"
]
},
"subtitle": {
"type": [
"string",
"null"
]
},
"style": {
"type": [
"string",
"null"
],
"enum": [
"calligraphy",
"clean"
]
},
"shapeStyle": {
"type": [
"string",
"null"
],
"enum": [
"calligraphy",
"clean"
]
},
"nodes": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"shape": {
"type": [
"string",
"null"
],
"enum": [
"rectangle",
"rounded-rect",
"circle",
"ellipse",
"diamond",
"triangle",
"parallelogram",
"hexagon",
"star",
"pentagon",
"octagon",
"trapezoid",
"process",
"decision",
"terminal",
"data-io",
"document",
"predefined-process",
"manual-input",
"pill",
"cloud",
"callout-bubble",
"underline-only",
"cylinder",
"database",
"banner",
"tag",
"shield",
"cross",
"arrow-shape",
"queue"
]
},
"text": {
"type": "string"
},
"style": {
"type": [
"object",
"null"
],
"properties": {
"fill": {
"type": [
"string",
"null"
]
},
"stroke": {
"type": [
"string",
"null"
]
},
"strokeWidth": {
"type": [
"number",
"null"
]
},
"opacity": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 1
},
"cornerRadius": {
"type": [
"number",
"null"
]
},
"shadow": {
"type": [
"boolean",
"null"
]
},
"shadowLevel": {
"type": [
"string",
"null"
],
"enum": [
"sm",
"md",
"lg"
]
},
"fontSize": {
"type": [
"number",
"null"
]
},
"fontColor": {
"type": [
"string",
"null"
]
},
"lineStyle": {
"type": [
"string",
"null"
],
"enum": [
"solid",
"dashed",
"dotted",
"dash-dot",
"long-dash"
],
"description": "Per-node outline line style. Excludes \"calligraphy\" — that mode is set per-spec via `defaultShapeLineStyle: \"calligraphy\"`, not per-node."
},
"iconColor": {
"type": [
"string",
"null"
]
},
"iconColors": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"required": [
"fill",
"stroke",
"strokeWidth",
"opacity",
"cornerRadius",
"shadow",
"shadowLevel",
"fontSize",
"fontColor",
"lineStyle",
"iconColor",
"iconColors"
]
},
"width": {
"type": [
"number",
"null"
],
"minimum": 0
},
"height": {
"type": [
"number",
"null"
],
"minimum": 0
},
"icon": {
"type": [
"string",
"null"
]
},
"iconKeywords": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
},
"hidden": {
"type": [
"boolean",
"null"
]
},
"group": {
"type": [
"string",
"null"
]
},
"chart": {
"type": [
"object",
"null"
],
"properties": {
"type": {
"type": "string",
"enum": [
"pie",
"donut",
"bar",
"sparkline",
"line"
]
},
"data": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"label": {
"type": [
"string",
"null"
],
"maxLength": 2000
},
"value": {
"type": "number"
},
"color": {
"type": [
"string",
"null"
],
"pattern": "^#[0-9a-fA-F]{3}([0-9a-fA-F]{3})?$"
}
},
"additionalProperties": false,
"required": [
"label",
"value",
"color"
]
},
"maxItems": 64
},
"series": {
"type": [
"array",
"null"
],
"items": {
"type": "number"
},
"maxItems": 512
},
"innerRadiusRatio": {
"type": [
"number",
"null"
],
"minimum": 0.1,
"maximum": 0.85
},
"showLabels": {
"type": [
"boolean",
"null"
]
},
"showValues": {
"type": [
"boolean",
"null"
]
},
"area": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false,
"required": [
"type",
"data",
"series",
"innerRadiusRatio",
"showLabels",
"showValues",
"area"
]
},
"kpi": {
"type": [
"object",
"null"
],
"properties": {
"value": {
"type": "string",
"maxLength": 2000
},
"label": {
"type": [
"string",
"null"
],
"maxLength": 2000
},
"delta": {
"type": [
"object",
"null"
],
"properties": {
"text": {
"type": "string",
"maxLength": 2000
},
"direction": {
"type": [
"string",
"null"
],
"enum": [
"up",
"down",
"flat"
]
},
"invertColor": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false,
"required": [
"text",
"direction",
"invertColor"
]
},
"sparkline": {
"type": [
"array",
"null"
],
"items": {
"type": "number"
},
"maxItems": 512
}
},
"additionalProperties": false,
"required": [
"value",
"label",
"delta",
"sparkline"
]
},
"animationLoop": {
"type": [
"string",
"null"
],
"enum": [
"once",
"2",
"3",
"5",
"infinite"
]
}
},
"additionalProperties": false,
"required": [
"id",
"shape",
"text",
"style",
"width",
"height",
"icon",
"iconKeywords",
"hidden",
"group",
"chart",
"kpi",
"animationLoop"
]
},
"description": "Structured node definitions. Required when not using prompt mode."
},
"edges": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"target": {
"type": "string"
},
"label": {
"type": [
"string",
"null"
]
},
"lineStyle": {
"type": [
"string",
"null"
],
"enum": [
"calligraphy",
"block-arrow",
"solid",
"dashed",
"dotted",
"dash-dot",
"long-dash"
]
},
"connectorType": {
"type": [
"string",
"null"
],
"enum": [
"straight",
"curved",
"elbow",
"orthogonal",
"bezier"
]
},
"sourceArrow": {
"type": [
"string",
"null"
],
"description": "Arrowhead style at the edge source end. Options: open (default) | triangle | diamond | circle | bar | dot | none."
},
"targetArrow": {
"type": [
"string",
"null"
],
"description": "Arrowhead style at the edge target end. Options: open (default) | triangle | diamond | circle | bar | dot | none."
},
"style": {
"type": [
"object",
"null"
],
"properties": {
"stroke": {
"type": [
"string",
"null"
]
},
"strokeWidth": {
"type": [
"number",
"null"
]
},
"opacity": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 1
},
"fill": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false,
"required": [
"stroke",
"strokeWidth",
"opacity",
"fill"
]
},
"hidden": {
"type": [
"boolean",
"null"
]
},
"animate": {
"type": [
"string",
"null"
],
"enum": [
"none",
"flow",
"pulse",
"glow",
"trace",
"wave",
"lightning",
"beat",
"comet"
],
"description": "Connector animation. Options: none (default) | flow (dashes march) | pulse (opacity breathing) | glow (stroke-width pulse) | trace (bright dot travels along) | wave (large stroke-width oscillation). SVG-only — exports to PNG/WebP capture one frozen frame."
},
"animateSpeed": {
"type": [
"string",
"null"
],
"enum": [
"slow",
"medium",
"fast"
],
"description": "Animation speed. Options: slow (3s cycle) | medium (2s, default) | fast (1s)."
},
"blockArrowSize": {
"anyOf": [
{
"type": "string",
"enum": [
"small",
"medium",
"large"
]
},
{
"type": "number",
"minimum": 1,
"maximum": 60
}
],
"description": "Block Arrow size for this edge (only when arrowStyle is \"block\"). Preset names: \"small\" (slim) | \"medium\" (default) | \"large\" (chunky). OR a raw body half-width in px (1–60); head dimensions scale proportionally."
},
"arrowStyle": {
"type": [
"string",
"null"
],
"enum": [
"calligraphy",
"clean",
"block"
],
"description": "Per-edge connector aesthetic mode (overrides defaultArrowStyle). Options: \"calligraphy\" | \"clean\" | \"block\". Orthogonal to lineStyle (dash pattern); all 15 combinations are valid."
},
"loop": {
"type": [
"string",
"null"
],
"enum": [
"once",
"2",
"3",
"5",
"infinite"
],
"description": "Per-edge animation loop count override. Wins over the diagram-level `defaultSceneAnimationLoop`. Values are quoted strings: \"once\" | \"2\" | \"3\" | \"5\" | \"infinite\". Maps to SMIL repeatCount."
}
},
"additionalProperties": false,
"required": [
"source",
"target",
"label",
"lineStyle",
"connectorType",
"sourceArrow",
"targetArrow",
"style",
"hidden",
"animate",
"animateSpeed",
"blockArrowSize",
"arrowStyle",
"loop"
]
}
},
"layout": {
"type": [
"object",
"null"
],
"properties": {
"direction": {
"type": [
"string",
"null"
],
"enum": [
"TB",
"LR",
"BT",
"RL",
"radial",
"assorted"
]
},
"nodeSpacing": {
"type": [
"number",
"null"
],
"minimum": 0
},
"rankSpacing": {
"type": [
"number",
"null"
],
"minimum": 0
},
"padding": {
"type": [
"number",
"null"
],
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"direction",
"nodeSpacing",
"rankSpacing",
"padding"
]
},
"theme": {
"type": [
"object",
"null"
],
"properties": {
"preset": {
"type": [
"string",
"null"
]
},
"palette": {
"type": [
"object",
"null"
],
"properties": {
"primary": {
"type": [
"string",
"null"
]
},
"secondary": {
"type": [
"string",
"null"
]
},
"accent": {
"type": [
"string",
"null"
]
},
"background": {
"type": [
"string",
"null"
]
},
"text": {
"type": [
"string",
"null"
]
},
"border": {
"type": [
"string",
"null"
]
},
"nodeColors": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"required": [
"primary",
"secondary",
"accent",
"background",
"text",
"border",
"nodeColors"
]
},
"paletteSeed": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false,
"required": [
"preset",
"palette",
"paletteSeed"
]
},
"defaultLineStyle": {
"type": [
"string",
"null"
],
"enum": [
"calligraphy",
"block-arrow",
"solid",
"dashed",
"dotted",
"dash-dot",
"long-dash"
],
"description": "v1.45.2+ — Default DASH PATTERN applied to all edges that don't specify their own. Options: \"solid\" | \"dashed\" | \"dotted\" | \"dash-dot\" | \"long-dash\". Combines orthogonally with `defaultArrowStyle` (calligraphy/clean/block) for 15 total visual combinations. Legacy values \"calligraphy\" and \"block-arrow\" are still accepted for backward compat (the renderer maps them to defaultArrowStyle=\"calligraphy\"/\"block\" with lineStyle=\"solid\"); new callers should use `defaultArrowStyle` for the aesthetic mode."
},
"defaultArrowHead": {
"type": [
"string",
"null"
],
"description": "Default arrowhead style applied to all edges that don't specify their own."
},
"defaultConnector": {
"type": [
"string",
"null"
],
"enum": [
"straight",
"curved",
"elbow",
"orthogonal",
"bezier"
],
"description": "Default connector type applied to all edges that don't specify their own."
},
"defaultShadow": {
"type": [
"string",
"null"
],
"enum": [
"none",
"sm",
"md",
"lg"
],
"description": "Default shadow level applied to all nodes."
},
"defaultShapeLineStyle": {
"type": [
"string",
"null"
],
"enum": [
"calligraphy",
"block-arrow",
"solid",
"dashed",
"dotted",
"dash-dot",
"long-dash"
],
"description": "Default line style for shape outlines (node borders). v1.44.1 — also drives shape rendering mode: \"calligraphy\" gives hand-drawn rough shapes (ink-ribbon outlines); \"solid\" | \"dashed\" | \"dotted\" | \"dash-dot\" | \"long-dash\" give crisp geometric shapes with that outline pattern. Independent of edge/connector line style."
},
"defaultConnectorAnimate": {
"type": [
"string",
"null"
],
"enum": [
"none",
"flow",
"pulse",
"glow",
"trace",
"wave",
"lightning",
"beat",
"comet"
],
"description": "Animate every connector edge. Options: none (default) | flow (dashes march along the line) | pulse (gentle opacity breathing) | glow (subtle stroke-width pulse) | trace (bright dot traverses each edge) | wave (large stroke-width oscillation). SVG-only — exports to PNG / WebP / OG-image freeze on first frame."
},
"defaultConnectorAnimateSpeed": {
"type": [
"string",
"null"
],
"enum": [
"slow",
"medium",
"fast"
],
"description": "Animation speed when defaultConnectorAnimate is set. Options: slow (3s cycle) | medium (2s, default) | fast (1s)."
},
"defaultSceneAnimation": {
"type": [
"string",
"null"
],
"enum": [
"none",
"fade",
"zoom",
"zoom-pan",
"flow",
"wave-sweep",
"build-up",
"flow-zoom-pan"
],
"description": "Whole-visual reveal animation. Plays ONCE when the SVG is displayed, freezes at the final state. Options: none (default) | fade (entire visual fades in) | zoom (scales in from 70% to 100%) | zoom-pan (Ken Burns camera move) | flow (each node + edge appears sequentially in spec order). Orthogonal to defaultConnectorAnimate — both can run together. SVG-only — PNG / WebP exports show the fully-revealed final state (rasteriser ignores SMIL; static attrs hold the final value). Animated GIF / MP4 client-side encoder ticks the scene through."
},
"defaultSceneAnimationSpeed": {
"type": [
"string",
"null"
],
"enum": [
"slow",
"medium",
"fast"
],
"description": "Scene animation speed. Options: slow (1.5× duration) | medium (default) | fast (0.6× duration)."
},
"defaultSceneAnimationLoop": {
"type": [
"string",
"null"
],
"enum": [
"once",
"2",
"3",
"5",
"infinite"
],
"description": "Animation loop count. v1.50.9+ — applies to BOTH connector animations (flow / pulse / glow / wave / trace / lightning / beat / comet) AND scene animations (fade / zoom / zoom-pan / flow / wave-sweep / build-up / flow-zoom-pan). Options (all quoted strings): \"once\" (default — plays once and freezes) | \"2\" | \"3\" | \"5\" (repeat that many times then freeze) | \"infinite\" (loop forever; best for live presentations and the historical default for connector animations pre-v1.50.9). Maps to SMIL repeatCount."
},
"defaultTitleStyle": {
"type": [
"string",
"null"
],
"enum": [
"plain",
"accent-bar",
"underline",
"boxed"
],
"description": "Title decoration treatment. Options: \"plain\" (default, just the title text), \"accent-bar\" (small accent-coloured vertical bar to the left of the title), \"underline\" (accent-coloured horizontal stroke below the title), \"boxed\" (title rendered in a subtle bordered + drop-shadowed pill — strongest framing). Affects only the diagram title, not subtitles or section headers."
},
"defaultDividerStyle": {
"type": [
"string",
"null"
],
"enum": [
"subtle",
"normal",
"bold",
"dashed",
"dotted",
"none"
],
"description": "Divider / grid-line / table-border style. Governs the structural rule-lines a diagram emits: matrix grid lines, gantt phase column dividers, sequence lifelines, swimlane (process-flow) lane boundaries. Options: \"subtle\" (barely-there hairline), \"normal\" (default — pre-v1.55.0 baseline of 1 px / 25 % opacity), \"bold\" (emphasised grid presence), \"dashed\" (6,4 dasharray editorial feel), \"dotted\" (1,3 dasharray lightweight rhythm), \"none\" (no divider emission — cells separated only by colour banding). Useful for comparison tables (try \"bold\") or minimalist matrices (try \"none\")."
},
"defaultBlockArrowSize": {
"anyOf": [
{
"type": "string",
"enum": [
"small",
"medium",
"large"
]
},
{
"type": "number",
"minimum": 1,
"maximum": 60
}
],
"description": "Default Block Arrow size when `defaultArrowStyle` (or per-edge arrowStyle) is \"block\". Options: \"small\" (slim — body ~14 px) | \"medium\" (default — body ~24 px) | \"large\" (chunky — body ~36 px). Or a raw body half-width number in px (1–60); head dimensions scale proportionally. Per-edge `blockArrowSize` overrides this default."
},
"defaultArrowStyle": {
"type": [
"string",
"null"
],
"enum": [
"calligraphy",
"clean",
"block"
],
"description": "Connector aesthetic mode applied to all edges that don't set their own `arrowStyle`. Options: \"calligraphy\" (default — hand-drawn ink-ribbon connectors) | \"clean\" (standard stroked-line connectors) | \"block\" (chunky outlined block-arrow connectors with integrated triangular head). Orthogonal to defaultLineStyle (which now controls dash pattern only) — all 15 combinations of arrowStyle × lineStyle are valid."
},
"ganttHolidays": {
"type": [
"array",
"null"
],
"items": {
"type": "string",
"maxLength": 32
},
"maxItems": 200,
"description": "Gantt-only: ISO 8601 holiday dates (e.g. [\"2026-12-25\", \"2026-01-01\"]). Rendered as gray vertical stripes alongside Sat/Sun (always weekend). Only applies in date-driven mode (every node has start/end). Other diagram types ignore this field."
},
"pyramid": {
"type": [
"object",
"null"
],
"properties": {
"tierLabels": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 50
},
"tierValues": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"maxItems": 50
},
"inverted": {
"type": [
"boolean",
"null"
]
},
"tipRatio": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 0.95
}
},
"additionalProperties": false,
"description": "Pyramid-only payload. Required when type=\"pyramid\". Fields: tierLabels (string[], 1..50, ordered base→tip), tierValues (optional string[]), inverted (boolean), tipRatio (0..0.95, default 0.15). Bloom's Taxonomy, Maslow's Hierarchy, Capability Maturity, DIKW.",
"required": [
"tierLabels",
"tierValues",
"inverted",
"tipRatio"
]
},
"funnel": {
"type": [
"object",
"null"
],
"properties": {
"stageLabels": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 50
},
"stageValues": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"maxItems": 50
},
"dropOff": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"maxItems": 50
},
"bottomRatio": {
"type": [
"number",
"null"
],
"minimum": 0.05,
"maximum": 0.99
}
},
"additionalProperties": false,
"description": "Funnel-only payload. Required when type=\"funnel\". Fields: stageLabels (string[], 1..50, ordered top→bottom), stageValues (optional string[]), dropOff (optional string[] of length stageLabels-1), bottomRatio (0.05..0.99, default 0.30). Sales pipeline, AARRR, ToFu/MoFu/BoFu.",
"required": [
"stageLabels",
"stageValues",
"dropOff",
"bottomRatio"
]
},
"radar": {
"type": [
"object",
"null"
],
"properties": {
"axes": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 3,
"maxItems": 50
},
"series": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": [
"string",
"null"
]
},
"values": {
"type": "array",
"items": {
"type": "number"
},
"maxItems": 50
}
},
"additionalProperties": false,
"required": [
"name",
"values"
]
},
"minItems": 1,
"maxItems": 10
},
"maxValue": {
"type": [
"number",
"null"
],
"minimum": 1
},
"rings": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 10
}
},
"additionalProperties": false,
"description": "Radar/spider-chart payload. Required when type=\"radar\". Fields: axes (string[], 3..50), series ({name, values: number[]}[], 1..10), maxValue (default 100), rings (default 4). Use multiple series for comparison overlays — first solid, rest dashed at 50% opacity.",
"required": [
"axes",
"series",
"maxValue",
"rings"
]
},
"iconStyle": {
"type": [
"string",
"null"
],
"description": "Icon rendering style. \"clean-mono\" = precise strokes + single color, \"clean-colorful\" = precise strokes + vibrant colors, \"calligraphy-mono\" = hand-drawn ink + single color, \"calligraphy-colorful\" = hand-drawn ink + vibrant colors, \"none\" = hide icons."
},
"fontFamily": {
"type": [
"string",
"null"
],
"description": "Font family for diagram text. Options: inter, poppins (sans-serif); playfair (serif); kalam, handlee (handwritten); fredoka (display); mono (monospace). Omit for style-matched default (Handlee for calligraphy, Inter for clean)."
},
"matrixColumns": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Column header labels for 2D matrix grid (e.g., [\"High Vision\", \"Low Vision\"])."
},
"matrixRows": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Row header labels for 2D matrix grid (e.g., [\"High Execution\", \"Low Execution\"])."
},
"xAxisLabel": {
"type": [
"string",
"null"
],
"description": "X-axis title for 2D matrix grid (e.g., \"Completeness of Vision\")."
},
"yAxisLabel": {
"type": [
"string",
"null"
],
"description": "Y-axis title for 2D matrix grid (e.g., \"Ability to Execute\")."
},
"matrixItemStyle": {
"type": [
"string",
"null"
],
"enum": [
"card",
"dot",
"text",
"badge"
],
"description": "Item display style for matrix diagrams. \"card\" (default) = rectangular cards, \"dot\" = scatter points, \"text\" = plain text, \"badge\" = compact pills."
},
"metadata": {
"type": [
"object",
"null"
],
"properties": {
"size": {
"type": [
"object",
"null"
],
"properties": {
"preset": {
"type": [
"string",
"null"
],
"maxLength": 64,
"description": "Visual size preset id from shared/visual-sizes.ts catalog (e.g. \"16x9-presentation\", \"ig-square\", \"youtube-thumb\"). Describes the EXPORT TARGET (PNG / PDF / PPTX render dimensions), NOT the canvas constraint at generation time. Mutually exclusive with width + height (preset wins when both are present)."
},
"width": {
"type": [
"integer",
"null"
],
"minimum": 320,
"maximum": 4096,
"description": "Custom export-target width in pixels. 320..4096. Used when no preset matches the desired output dimensions. Pair with `height` for full custom dims; pair with `aspect` for aspect-driven sizing."
},
"height": {
"type": [
"integer",
"null"
],
"minimum": 320,
"maximum": 4096,
"description": "Custom export-target height in pixels. 320..4096. Used with `width` for full custom dims, or with `aspect` for aspect-driven sizing."
},
"aspect": {
"type": [
"string",
"null"
],
"pattern": "^\\d+(\\.\\d+)?:\\d+(\\.\\d+)?$",
"description": "Canonical \"W:H\" aspect emitted alongside preset / custom dims for fast consumer reads. Accepts integer or decimal ratios. Examples: \"16:9\", \"9:16\", \"1:1\", \"1.91:1\" (OG card)."
},
"bestFit": {
"type": [
"boolean",
"null"
],
"description": "v1.65.1+ Phase 3 opt-in flag. When `true` (alongside `metadata.bestFit` AND `metadata.targetAspect`), signals the server orchestrator to re-invoke the Designer with the target aspect ratio so the layout reflows to fit the export shape. Feature-flagged behind `VISUAL_SIZES_PHASE3_ENABLED` server-side; when OFF the field round-trips through the response but the orchestrator follows the legacy Phase 1/2 path. Default: false."
}
},
"additionalProperties": false,
"description": "Visual-size persistence bag (v1.65.4+). Describes the EXPORT TARGET dimensions, NOT a canvas constraint at generation time. Round-trips through the response unchanged.",
"required": [
"preset",
"width",
"height",
"aspect",
"bestFit"
]
},
"bestFit": {
"type": [
"boolean",
"null"
],
"description": "v1.65.1+ Phase 3 server-side gate. When `true` + `targetAspect` is set + the server flag `VISUAL_SIZES_PHASE3_ENABLED` is on, the Designer is re-invoked with the target aspect ratio to reflow the layout. Independent of `metadata.size.bestFit`; the frontend mirrors this field when the toggle is on."
},
"targetAspect": {
"type": [
"string",
"null"
],
"maxLength": 16,
"description": "v1.65.1+ Phase 3 server-side aspect ratio. Accepts \"W:H\" forms (e.g. \"9:16\", \"16:9\", \"1:1\", \"1.91:1\"). Forwarded to the Designer when `bestFit` is on."
}
},
"additionalProperties": false,
"description": "Visual-size + Best-fit metadata bag (v1.65.4 -> v1.67.12). All fields optional; legacy callers without `metadata` are byte-identical to today. The server echoes `metadata.size` back on the response so integrators can confirm the field was honoured.",
"required": [
"size",
"bestFit",
"targetAspect"
]
}
},
"required": [
"prompt",
"type",
"sections",
"title",
"subtitle",
"style",
"shapeStyle",
"nodes",
"edges",
"layout",
"theme",
"defaultLineStyle",
"defaultArrowHead",
"defaultConnector",
"defaultShadow",
"defaultShapeLineStyle",
"defaultConnectorAnimate",
"defaultConnectorAnimateSpeed",
"defaultSceneAnimation",
"defaultSceneAnimationSpeed",
"defaultSceneAnimationLoop",
"defaultTitleStyle",
"defaultDividerStyle",
"defaultBlockArrowSize",
"defaultArrowStyle",
"ganttHolidays",
"pyramid",
"funnel",
"radar",
"iconStyle",
"fontFamily",
"matrixColumns",
"matrixRows",
"xAxisLabel",
"yAxisLabel",
"matrixItemStyle",
"metadata"
],
"additionalProperties": false
}