@salesforce/afv-skills 1.59.0 → 1.60.0

package/skills/tableau-next-asset-create/references/schemas/edit-dashboard/move_widget.json

@@ -0,0 +1,30 @@
+{
+  "title": "move_widget",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["operation", "pageName", "placement"],
+  "properties": {
+    "operation": { "const": "move_widget" },
+    "pageName": { "type": "string", "description": "Dev name of the page the widget is on." },
+    "placement": {
+      "type": "object",
+      "description": "New grid coordinates for the widget on the same page.",
+      "required": ["name"],
+      "properties": {
+        "id": { "type": "string", "description": "Optional placement id (rarely needed to author; usually server-assigned)." },
+        "name": { "type": "string", "description": "Name of the widget to reposition." },
+        "label": { "type": "string", "description": "Optional placement-level label override." },
+        "description": { "type": "string", "description": "Optional placement-level description." },
+        "row": { "type": "integer", "description": "New 1-based grid row." },
+        "column": { "type": "integer", "description": "New 1-based grid column." },
+        "rowspan": { "type": "integer", "description": "New height in rows." },
+        "colspan": { "type": "integer", "description": "New width in columns." }
+      }
+    }
+  },
+  "example": {
+    "operation": "move_widget",
+    "pageName": "page_1",
+    "placement": { "name": "viz_1", "row": 5, "column": 25, "rowspan": 20, "colspan": 24 }
+  }
+}

package/skills/tableau-next-asset-create/references/schemas/edit-dashboard/move_widget_to_page.json

@@ -0,0 +1,30 @@
+{
+  "title": "move_widget_to_page",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["operation", "pageName", "placement"],
+  "properties": {
+    "operation": { "const": "move_widget_to_page" },
+    "pageName": { "type": "string", "description": "Dev name of the TARGET page the widget is moved to." },
+    "placement": {
+      "type": "object",
+      "description": "The widget to move (by name) and its placement on the target page.",
+      "required": ["name"],
+      "properties": {
+        "id": { "type": "string", "description": "Optional placement id (rarely needed to author; usually server-assigned)." },
+        "name": { "type": "string", "description": "Name of the widget to move." },
+        "label": { "type": "string", "description": "Optional placement-level label override." },
+        "description": { "type": "string", "description": "Optional placement-level description." },
+        "row": { "type": "integer", "description": "1-based grid row on the target page." },
+        "column": { "type": "integer", "description": "1-based grid column on the target page." },
+        "rowspan": { "type": "integer", "description": "Height in rows." },
+        "colspan": { "type": "integer", "description": "Width in columns." }
+      }
+    }
+  },
+  "example": {
+    "operation": "move_widget_to_page",
+    "pageName": "page_2",
+    "placement": { "name": "viz_1", "row": 1, "column": 1, "rowspan": 20, "colspan": 24 }
+  }
+}

package/skills/tableau-next-asset-create/references/schemas/edit-dashboard/place_widget_on_page.json

@@ -0,0 +1,30 @@
+{
+  "title": "place_widget_on_page",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["operation", "pageName", "placement"],
+  "properties": {
+    "operation": { "const": "place_widget_on_page" },
+    "pageName": { "type": "string", "description": "Dev name of the page to place the widget on, e.g. \"page_1\"." },
+    "placement": {
+      "type": "object",
+      "description": "Grid placement referencing an already-built widget by name.",
+      "required": ["name"],
+      "properties": {
+        "id": { "type": "string", "description": "Optional placement id (rarely needed to author; usually server-assigned)." },
+        "name": { "type": "string", "description": "Name of the widget to place (the key set when it was built)." },
+        "label": { "type": "string", "description": "Optional placement-level label override." },
+        "description": { "type": "string", "description": "Optional placement-level description." },
+        "row": { "type": "integer", "description": "1-based grid row." },
+        "column": { "type": "integer", "description": "1-based grid column." },
+        "rowspan": { "type": "integer", "description": "Height in rows." },
+        "colspan": { "type": "integer", "description": "Width in columns (grid is 48 wide)." }
+      }
+    }
+  },
+  "example": {
+    "operation": "place_widget_on_page",
+    "pageName": "page_1",
+    "placement": { "name": "text_1", "row": 1, "column": 1, "rowspan": 4, "colspan": 24 }
+  }
+}

package/skills/tableau-next-asset-create/references/schemas/edit-dashboard/remove_widget_from_dashboard.json

@@ -0,0 +1,16 @@
+{
+  "title": "remove_widget_from_dashboard",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["operation", "widgetName"],
+  "properties": {
+    "operation": { "const": "remove_widget_from_dashboard" },
+    "widgetName": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S",
+      "description": "Name/key of the widget definition to remove, including every placement across all dashboard pages. Source it the same way as widget.name elsewhere: read it back via render_dashboard, or reuse the widget.name supplied to an earlier upsert_*_widget in this same draft/batch. Never invent it. Distinct from remove_widget_from_page, which only unplaces one page's placement and leaves the definition behind (see edit-dashboard.md §6)."
+    }
+  },
+  "example": { "operation": "remove_widget_from_dashboard", "widgetName": "text_1" }
+}

package/skills/tableau-next-asset-create/references/schemas/edit-dashboard/remove_widget_from_page.json

@@ -0,0 +1,26 @@
+{
+  "title": "remove_widget_from_page",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["operation", "pageName", "placement"],
+  "properties": {
+    "operation": { "const": "remove_widget_from_page" },
+    "pageName": { "type": "string", "description": "Dev name of the page to remove the widget placement from." },
+    "placement": {
+      "type": "object",
+      "description": "Identifies the placement to remove by widget name.",
+      "required": ["name"],
+      "properties": {
+        "id": { "type": "string", "description": "Optional placement id (rarely needed to author; usually server-assigned)." },
+        "name": { "type": "string", "description": "Name of the widget whose placement is removed from this page." },
+        "label": { "type": "string", "description": "Optional placement-level label (not required to identify the placement — name is sufficient)." },
+        "description": { "type": "string", "description": "Optional placement-level description." }
+      }
+    }
+  },
+  "example": {
+    "operation": "remove_widget_from_page",
+    "pageName": "page_1",
+    "placement": { "name": "text_1" }
+  }
+}

package/skills/tableau-next-asset-create/references/schemas/edit-dashboard/rename_page.json

@@ -0,0 +1,28 @@
+{
+  "title": "rename_page",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["operation", "page"],
+  "properties": {
+    "operation": { "const": "rename_page" },
+    "layoutName": {
+      "type": "string",
+      "description": "Dev name of the layout the page is in. Optional; defaults to the first layout."
+    },
+    "page": {
+      "type": "object",
+      "description": "Identifies the page by name and sets its new label.",
+      "required": ["name", "label"],
+      "properties": {
+        "id": { "type": "string", "description": "Optional page id (rarely needed to author; usually server-assigned)." },
+        "name": { "type": "string", "description": "Existing page dev name to rename." },
+        "label": { "type": "string", "description": "New display label / tab title." },
+        "description": { "type": "string", "description": "Optional page description." }
+      }
+    }
+  },
+  "example": {
+    "operation": "rename_page",
+    "page": { "name": "page_2", "label": "Regional detail" }
+  }
+}

package/skills/tableau-next-asset-create/references/schemas/edit-dashboard/save_dashboard.json

@@ -0,0 +1,18 @@
+{
+  "title": "save_dashboard",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["operation"],
+  "properties": {
+    "operation": { "const": "save_dashboard" },
+    "dashboardIdOrApiName": {
+      "type": "string",
+      "description": "The id (0FK...) or apiName of the dashboard to save. Optional; defaults to the dashboard the batch targets."
+    }
+  },
+  "description": "Control operation. Standalone (sole operation in the batch): commits whatever draft is already staged on the dashboard. In a mixed batch: persists once after the other operations in that same batch succeed. The top-level autosave flag is ignored when save_dashboard is present.",
+  "example": {
+    "operation": "save_dashboard",
+    "dashboardIdOrApiName": "0FK000000000123"
+  }
+}

package/skills/tableau-next-asset-create/references/schemas/edit-dashboard/undo.json

@@ -0,0 +1,11 @@
+{
+  "title": "undo",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["operation"],
+  "properties": {
+    "operation": { "const": "undo" }
+  },
+  "description": "Control operation. Standalone (sole operation in the batch): reverts the last staged change. In a mixed batch: cancels all incoming operations in that batch (nothing else in the batch takes effect).",
+  "example": { "operation": "undo" }
+}

package/skills/tableau-next-asset-create/references/schemas/edit-dashboard/upsert_button_widget.json

@@ -0,0 +1,69 @@
+{
+  "title": "upsert_button_widget",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["operation", "widget"],
+  "properties": {
+    "operation": { "const": "upsert_button_widget" },
+    "widget": {
+      "type": "object",
+      "description": "Complete button widget definition for create or full replacement. Omitted fields are dropped on replacement. No data source. Upsert defines the widget only; it neither places it nor changes existing placements.",
+      "required": ["type", "name"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Existing widget ID. Required when fully replacing a persisted widget; omit when creating a widget. Never invent this value. An unsaved draft widget has no ID and may be replaced by matching widget.name."
+        },
+        "type": { "const": "button" },
+        "name": {
+          "type": "string",
+          "description": "Stable widget key, e.g. \"button_1\". On persisted replacement, it must match the widget identified by id."
+        },
+        "label": { "type": "string", "description": "Display label." },
+        "description": { "type": "string", "description": "Optional widget description (distinct from label)." },
+        "actions": {
+          "type": "array",
+          "description": "Optional click/select interactions (navigate, run a flow, set a parameter, set a filter, record action) — the button's primary use case. Full per-type shape: _shared-widget-fields.json.",
+          "items": { "type": "object", "required": ["actionType", "eventType"] }
+        },
+        "dynamicTokens": {
+          "type": "object",
+          "description": "Optional dynamic value bindings keyed by token name. Full shape: _shared-widget-fields.json.",
+          "additionalProperties": { "type": "object" }
+        },
+        "parameters": {
+          "type": "object",
+          "description": "Button widget parameters.",
+          "properties": {
+            "text": { "type": "string", "description": "Button caption, e.g. \"View Details\"." },
+            "alignmentX": { "type": "string", "description": "Horizontal text alignment, e.g. \"center\"." },
+            "alignmentY": { "type": "string", "description": "Vertical text alignment, e.g. \"middle\"." },
+            "fontSize": { "type": "integer", "description": "Font size, e.g. 14." },
+            "symbol": {
+              "type": "object",
+              "description": "Optional icon shown alongside the caption.",
+              "properties": {
+                "name": { "type": "string", "description": "Icon name." },
+                "position": { "type": "string", "description": "Icon position relative to the caption, e.g. \"left\"." }
+              }
+            },
+            "widgetStyle": { "type": "object", "description": "ButtonStyle (WidgetStyle + fontColor/textStyle). Full shape: _shared-widget-fields.json#/styleBlocks/ButtonStyle." },
+            "hoverStyle": { "type": "object", "description": "ButtonStyle applied on hover. Full shape: _shared-widget-fields.json#/styleBlocks/ButtonStyle." }
+          }
+        }
+      }
+    }
+  },
+  "example": {
+    "operation": "upsert_button_widget",
+    "widget": {
+      "type": "button",
+      "name": "button_1",
+      "parameters": {
+        "text": "View Details",
+        "alignmentX": "center",
+        "alignmentY": "middle"
+      }
+    }
+  }
+}

package/skills/tableau-next-asset-create/references/schemas/edit-dashboard/upsert_container_widget.json

@@ -0,0 +1,88 @@
+{
+  "title": "upsert_container_widget",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["operation", "widget"],
+  "properties": {
+    "operation": { "const": "upsert_container_widget" },
+    "widget": {
+      "type": "object",
+      "description": "Complete container (layout grouping) widget definition for create or full replacement. Omitted fields are dropped on replacement. Styling lives under parameters.widgetStyle. An optional backgroundSource sets a background image asset { id, name }. Upsert defines the widget only; it neither places it nor changes existing placements.",
+      "required": ["type", "name"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Existing widget ID. Required when fully replacing a persisted widget; omit when creating a widget. Never invent this value. An unsaved draft widget has no ID and may be replaced by matching widget.name."
+        },
+        "type": { "const": "container" },
+        "name": {
+          "type": "string",
+          "description": "Stable widget key, e.g. \"container_1\". On persisted replacement, it must match the widget identified by id."
+        },
+        "label": { "type": "string", "description": "Display label." },
+        "description": { "type": "string", "description": "Optional widget description (distinct from label)." },
+        "actions": {
+          "type": "array",
+          "description": "Optional click/select interactions (navigate, run a flow, set a parameter, set a filter, record action). Full per-type shape: _shared-widget-fields.json.",
+          "items": { "type": "object", "required": ["actionType", "eventType"] }
+        },
+        "dynamicTokens": {
+          "type": "object",
+          "description": "Optional dynamic value bindings keyed by token name. Full shape: _shared-widget-fields.json.",
+          "additionalProperties": { "type": "object" }
+        },
+        "backgroundSource": {
+          "type": "object",
+          "description": "Optional background image asset reference.",
+          "properties": {
+            "id": { "type": "string", "description": "Asset record id." },
+            "name": { "type": "string", "description": "Asset apiName." }
+          }
+        },
+        "parameters": {
+          "type": "object",
+          "description": "Container widget parameters. widgetStyle carries the container's fill, border, and background-image styling.",
+          "properties": {
+            "widgetStyle": {
+              "type": "object",
+              "description": "Container styling.",
+              "properties": {
+                "backgroundColor": { "type": "string", "description": "Background fill color hex, e.g. \"#F3F3F3\"." },
+                "borderColor": { "type": "string", "description": "Border color hex." },
+                "borderWidth": { "type": "integer", "description": "Border width in px." },
+                "borderRadius": { "type": "integer", "description": "Border corner radius in px." },
+                "borderEdges": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Which edges show a border, e.g. [\"top\", \"bottom\", \"left\", \"right\"]."
+                },
+                "background": {
+                  "type": "object",
+                  "description": "Background-image styling (applies to backgroundSource).",
+                  "properties": {
+                    "alignmentX": { "type": "string", "description": "Horizontal alignment of the background image." },
+                    "alignmentY": { "type": "string", "description": "Vertical alignment of the background image." },
+                    "imageScale": {
+                      "type": "string",
+                      "enum": ["fitToWidth", "fitToHeight", "fill", "original"],
+                      "description": "Background image scale mode."
+                    },
+                    "opacity": { "type": "integer", "description": "Background image opacity 0-100." }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "example": {
+    "operation": "upsert_container_widget",
+    "widget": {
+      "type": "container",
+      "name": "container_1",
+      "label": "KPI group"
+    }
+  }
+}

package/skills/tableau-next-asset-create/references/schemas/edit-dashboard/upsert_filter_widget.json

@@ -0,0 +1,146 @@
+{
+  "title": "upsert_filter_widget",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["operation", "widget"],
+  "properties": {
+    "operation": { "const": "upsert_filter_widget" },
+    "widget": {
+      "type": "object",
+      "description": "Complete filter widget definition for create or full replacement. Omitted fields are dropped on replacement. source is the data source { id, name }; parameters carry the view type and the field to filter on. Upsert defines the widget only; it neither places it nor changes existing placements.",
+      "required": ["type", "name"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Existing widget ID. Required when fully replacing a persisted widget; omit when creating a widget. Never invent this value. An unsaved draft widget has no ID and may be replaced by matching widget.name."
+        },
+        "type": { "const": "filter" },
+        "name": {
+          "type": "string",
+          "description": "Stable widget key, e.g. \"filter_1\". On persisted replacement, it must match the widget identified by id."
+        },
+        "label": { "type": "string", "description": "Display label, e.g. \"Region\"." },
+        "description": { "type": "string", "description": "Optional widget description (distinct from label)." },
+        "actions": {
+          "type": "array",
+          "description": "Optional click/select interactions. Full per-type shape: _shared-widget-fields.json.",
+          "items": { "type": "object", "required": ["actionType", "eventType"] }
+        },
+        "dynamicTokens": {
+          "type": "object",
+          "description": "Optional dynamic value bindings keyed by token name. Full shape: _shared-widget-fields.json.",
+          "additionalProperties": { "type": "object" }
+        },
+        "source": {
+          "type": "object",
+          "description": "Data source reference.",
+          "properties": {
+            "id": { "type": "string", "description": "Data source record id." },
+            "name": { "type": "string", "description": "Data source apiName." }
+          }
+        },
+        "initialValues": {
+          "type": "object",
+          "description": "Optional default filter state applied when the dashboard loads.",
+          "properties": {
+            "details": {
+              "type": "array",
+              "description": "FilterDetails[] — { fieldName, operator, values }. operator is a large enum (Equals, Contains, Between, In, IsEmpty, LastNDays, PreviousQuarter, StartsWith, …, ~60 values covering text/date/numeric comparisons); read this field's live schema for the exact enum before authoring one rather than guessing a value.",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "fieldName": { "type": "string" },
+                  "operator": { "type": "string", "description": "See field description above — large enum, don't guess a value." },
+                  "values": { "type": "array" }
+                }
+              }
+            }
+          }
+        },
+        "parameters": {
+          "description": "Filter widget parameters — shape depends on viewType. oneOf ListFilterParameters | ListCardFilterParameters | ToggleFilterParameters. Send only the fields for your chosen viewType.",
+          "oneOf": [
+            {
+              "title": "ListFilterParameters",
+              "type": "object",
+              "required": ["viewType", "isLabelHidden"],
+              "properties": {
+                "viewType": { "const": "list" },
+                "isLabelHidden": { "type": "boolean", "description": "Show or hide the filter widget's label. REQUIRED for viewType list/listcard." },
+                "filterOption": {
+                  "type": "object",
+                  "description": "Which field the filter targets and how it selects.",
+                  "properties": {
+                    "objectName": { "type": "string", "description": "Table/view name, e.g. \"Opportunity\"." },
+                    "fieldName": { "type": "string", "description": "Field to filter on, e.g. \"StageName\"." },
+                    "dataType": {
+                      "type": "string",
+                      "enum": ["Text", "Boolean", "Geo", "Date", "DateTime", "Number", "Currency", "Percentage"],
+                      "description": "Semantic data type of the filtered field (case-sensitive; must be one of the enum values). It selects the filter UI at render time: Text/Boolean/Geo render a value list, Date/DateTime a date picker, Number/Currency/Percentage a numeric range. Any other value (e.g. the JSON type \"string\") is rejected at render with \"Unsupported data type for filter\"."
+                    },
+                    "selectionType": { "type": "string", "enum": ["single", "multiple"], "description": "Single- or multi-select." }
+                  }
+                },
+                "widgetStyle": { "type": "object", "description": "WidgetStyle. Full shape: _shared-widget-fields.json#/styleBlocks/WidgetStyle." },
+                "titleStyle": { "type": "object", "description": "WidgetTextStyle for the label. Full shape: _shared-widget-fields.json#/styleBlocks/WidgetTextStyle." },
+                "valueStyle": { "type": "object", "description": "WidgetTextStyle for the values. Full shape: _shared-widget-fields.json#/styleBlocks/WidgetTextStyle." },
+                "receiveFilterSource": { "type": "object", "description": "Full shape: _shared-widget-fields.json#/receiveSources/receiveFilterSource." },
+                "receiveParameterSource": { "type": "object", "description": "Full shape: _shared-widget-fields.json#/receiveSources/receiveParameterSource." }
+              }
+            },
+            {
+              "title": "ListCardFilterParameters",
+              "type": "object",
+              "required": ["viewType", "isLabelHidden"],
+              "properties": {
+                "viewType": { "const": "listcard" },
+                "isLabelHidden": { "type": "boolean", "description": "Show or hide the filter widget's label. REQUIRED for viewType list/listcard." },
+                "filterOption": { "type": "object", "description": "Same shape as ListFilterParameters.filterOption above." },
+                "widgetStyle": { "type": "object", "description": "WidgetStyle. Full shape: _shared-widget-fields.json#/styleBlocks/WidgetStyle." },
+                "titleStyle": { "type": "object", "description": "WidgetTextStyle. Full shape: _shared-widget-fields.json#/styleBlocks/WidgetTextStyle." },
+                "valueStyle": { "type": "object", "description": "WidgetTextStyle. Full shape: _shared-widget-fields.json#/styleBlocks/WidgetTextStyle." },
+                "receiveFilterSource": { "type": "object", "description": "Full shape: _shared-widget-fields.json#/receiveSources/receiveFilterSource." },
+                "receiveParameterSource": { "type": "object", "description": "Full shape: _shared-widget-fields.json#/receiveSources/receiveParameterSource." }
+              }
+            },
+            {
+              "title": "ToggleFilterParameters",
+              "type": "object",
+              "required": ["viewType"],
+              "description": "isLabelHidden is NOT used by toggle — omit it here.",
+              "properties": {
+                "viewType": { "const": "toggle" },
+                "filterOption": { "type": "object", "description": "Same shape as ListFilterParameters.filterOption above." },
+                "widgetStyle": { "type": "object", "description": "WidgetStyle. Full shape: _shared-widget-fields.json#/styleBlocks/WidgetStyle." },
+                "textStyle": { "type": "object", "description": "ToggleTextStyle. Full shape: _shared-widget-fields.json#/styleBlocks/ToggleTextStyle." },
+                "defaultStyle": { "type": "object", "description": "ToggleDefaultStyle. Full shape: _shared-widget-fields.json#/styleBlocks/ToggleDefaultStyle." },
+                "selectedStyle": { "type": "object", "description": "ToggleSelectedStyle. Full shape: _shared-widget-fields.json#/styleBlocks/ToggleSelectedStyle." },
+                "receiveFilterSource": { "type": "object", "description": "Full shape: _shared-widget-fields.json#/receiveSources/receiveFilterSource." },
+                "receiveParameterSource": { "type": "object", "description": "Full shape: _shared-widget-fields.json#/receiveSources/receiveParameterSource." }
+              }
+            }
+          ]
+        }
+      }
+    }
+  },
+  "example": {
+    "operation": "upsert_filter_widget",
+    "widget": {
+      "type": "filter",
+      "name": "filter_1",
+      "label": "Stage",
+      "source": { "id": "0Fb000000000123", "name": "OpportunityDataSource" },
+      "parameters": {
+        "viewType": "list",
+        "filterOption": {
+          "objectName": "Opportunity",
+          "fieldName": "StageName",
+          "dataType": "Text",
+          "selectionType": "multiple"
+        },
+        "isLabelHidden": false
+      }
+    }
+  }
+}

package/skills/tableau-next-asset-create/references/schemas/edit-dashboard/upsert_metric_widget.json

@@ -0,0 +1,78 @@
+{
+  "title": "upsert_metric_widget",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["operation", "widget"],
+  "properties": {
+    "operation": { "const": "upsert_metric_widget" },
+    "widget": {
+      "type": "object",
+      "description": "Complete metric widget definition for create or full replacement. Omitted fields are dropped on replacement. source may reference the metric; parameters.metricOption carries the SDM identifiers. Upsert defines the widget only; it neither places it nor changes existing placements.",
+      "required": ["type", "name"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Existing widget ID. Required when fully replacing a persisted widget; omit when creating a widget. Never invent this value. An unsaved draft widget has no ID and may be replaced by matching widget.name."
+        },
+        "type": { "const": "metric" },
+        "name": {
+          "type": "string",
+          "description": "Stable widget key, e.g. \"metric_1\". On persisted replacement, it must match the widget identified by id."
+        },
+        "label": { "type": "string", "description": "Display label." },
+        "description": { "type": "string", "description": "Optional widget description (distinct from label)." },
+        "actions": {
+          "type": "array",
+          "description": "Optional click/select interactions. Full per-type shape: _shared-widget-fields.json.",
+          "items": { "type": "object", "required": ["actionType", "eventType"] }
+        },
+        "dynamicTokens": {
+          "type": "object",
+          "description": "Optional dynamic value bindings keyed by token name (e.g. referenced from metricOption.layout). Full shape: _shared-widget-fields.json.",
+          "additionalProperties": { "type": "object" }
+        },
+        "source": {
+          "type": "object",
+          "description": "Optional metric data source reference.",
+          "properties": {
+            "id": { "type": "string", "description": "Metric record id." },
+            "name": { "type": "string", "description": "Metric apiName." }
+          }
+        },
+        "parameters": {
+          "type": "object",
+          "description": "Metric widget parameters.",
+          "properties": {
+            "metricOption": {
+              "type": "object",
+              "description": "Metric layout and SDM information.",
+              "properties": {
+                "sdmApiName": { "type": "string", "description": "Semantic data model apiName, e.g. \"Revenue_SDM\"." },
+                "sdmId": { "type": "string", "description": "Semantic data model id (2SM...)." },
+                "showForecast": { "type": "boolean", "description": "Whether to show a forecast on the metric card." },
+                "layout": {
+                  "type": "object",
+                  "additionalProperties": true,
+                  "description": "Metric layout settings keyed by setting name. No fixed schema — pass through settings as given rather than inventing keys."
+                },
+                "metricCardVersion": { "type": "integer", "description": "Metric card rendering version." }
+              }
+            },
+            "widgetStyle": { "type": "object", "description": "MetricStyle (WidgetStyle + textColor). Full shape: _shared-widget-fields.json#/styleBlocks/MetricStyle." },
+            "receiveFilterSource": { "type": "object", "description": "Which published filters this widget listens to. Full shape: _shared-widget-fields.json#/receiveSources/receiveFilterSource." }
+          }
+        }
+      }
+    }
+  },
+  "example": {
+    "operation": "upsert_metric_widget",
+    "widget": {
+      "type": "metric",
+      "name": "metric_1",
+      "parameters": {
+        "metricOption": { "sdmApiName": "Revenue_SDM", "sdmId": "2SM000000000123" }
+      }
+    }
+  }
+}