Chart

{
  "type": "object",
  "description": "Chart content. The chart object keeps chart-specific fields together so slides and regions do not expose loose chart fields. OPF charts are `{ type, data }` where `data` is `{ columns, rows }`: the first column holds the category labels and every further column is one series. There are no `categories`, `series`, `labels` or `datasets` keys (the Chart.js and ECharts shape); write them as columns and rows. Example: `{ \"type\": \"column\", \"data\": { \"columns\": [\"Quarter\", \"Decks\"], \"rows\": [[\"Q1\", 3], [\"Q2\", 8], [\"Q3\", 21]] } }`.",
  "additionalProperties": false,
  "required": [
    "type",
    "data"
  ],
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "100pct-stacked-area",
        "100pct-stacked-bar",
        "100pct-stacked-column",
        "area",
        "bar",
        "box-and-whisker",
        "column",
        "combo",
        "doughnut",
        "filled-radar",
        "funnel",
        "histogram",
        "line",
        "line-with-markers",
        "pareto",
        "pie",
        "radar",
        "radar-with-markers",
        "scatter",
        "stacked-area",
        "stacked-bar",
        "stacked-column",
        "stacked-line",
        "stacked-line-with-markers",
        "treemap",
        "waterfall",
        "world"
      ],
      "description": "Chart type, an engine vocabulary validated directly (no catalog lookup): the chart types Aspose.Slides officially supports, plus 'combo' (clustered columns with line series, see 'line' and 'secondaryAxis'). Each engine maps a type to its own chart model; labels and picker groups are catalog display metadata.",
      "examples": [
        "column",
        "bar",
        "line",
        "pie",
        "doughnut",
        "area",
        "scatter",
        "radar",
        "waterfall",
        "funnel",
        "treemap",
        "stacked-column",
        "combo"
      ]
    },
    "data": {
      "oneOf": [
        {
          "$ref": "#/$defs/ChartData"
        },
        {
          "$ref": "#/$defs/DatasetRef"
        }
      ],
      "description": "Chart data. Inline data uses a tabular columns/rows shape; renderers convert rows to chart series internally. A DatasetRef ({ \"dataset\": \"<id>\" }) plots a top-level dataset instead. Data from a spreadsheet or file is imported into inline columns and rows, and its origin is recorded in data.source."
    },
    "mapping": {
      "$ref": "#/$defs/ChartMapping",
      "description": "Optional series mapping by column name: which column is the category, which is the X column of a scatter chart, and which columns are plotted, in order. Absent keeps the positional rule (first column the category, then the X column for scatter, every other column a series)."
    },
    "line": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "uniqueItems": true,
      "description": "Combo charts only (type 'combo'): the plotted series, by column name, that are drawn as lines with markers; every other plotted series is drawn as clustered columns. Absent: the last plotted series is the line. A combo chart keeps at least one column series, so a list that names every series draws the first one as columns. Column series are drawn, exported and listed in the legend first, then the line series on the primary axis, then those on the secondary axis, each in plotted order. A name that is not a column is a 'chart-mapping-unknown-column' error; a column that is not plotted is a 'chart-mapping-adapted' warning. On any other chart type it is ignored with a 'chart-option-adapted' warning.",
      "examples": [
        [
          "Margin"
        ]
      ]
    },
    "secondaryAxis": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "uniqueItems": true,
      "description": "Combo charts only: line series, by column name, plotted against a secondary value axis at the right of the plot. That axis has its own scale, and its tick labels use the number format of the first secondary series' column (DataColumn.format), for example '0%' for a margin. Absent: every series shares the primary value axis at the left. A name that is not a line series (see 'line') stays on the primary axis with a 'chart-mapping-adapted' warning; an unknown column is a 'chart-mapping-unknown-column' error. On any other chart type it is ignored with a 'chart-option-adapted' warning.",
      "examples": [
        [
          "Margin"
        ]
      ]
    },
    "axisTitles": {
      "$ref": "#/$defs/ChartAxisTitles",
      "description": "Optional axis titles. Absent keeps today's untitled axes. Supported on the chart types that have a category/value (or X/Y) axis pair (column, bar, line, area, scatter, and the histogram, pareto, waterfall and box-and-whisker constructs; the funnel construct takes a category title only; a combo chart also takes 'secondary' when it plots a series on the secondary axis); a title on a type without that axis (pie, doughnut, radar, treemap, map) is dropped with a 'chart-option-adapted' diagnostic by renderers and exporters."
    },
    "legend": {
      "type": "string",
      "enum": [
        "none",
        "top",
        "bottom",
        "left",
        "right"
      ],
      "description": "Optional legend position. 'none' hides the legend. Absent keeps today's behaviour exactly (a legend at the right of multi-series charts and of pie and doughnut charts, none for single-series charts). A named position shows the legend there even for a single-series chart. Of the Office 2016 constructs only box-and-whisker takes a legend; histogram, pareto, waterfall, funnel, treemap and map drop the option with a 'chart-option-adapted' diagnostic."
    },
    "dataLabels": {
      "oneOf": [
        {
          "type": "boolean"
        },
        {
          "$ref": "#/$defs/ChartDataLabels"
        }
      ],
      "description": "Optional data labels. true shows value labels at each type's default position, false (or absent) shows none, which is today's behaviour. Use the object form for the label content, position and separator."
    },
    "alt": {
      "type": "string",
      "description": "Text alternative for the chart: what the data shows (the point and the key numbers), not 'a chart' or 'bar chart'. The preview exposes it as the chart's accessible name (role img with aria-label) and the PowerPoint export writes it as the chart frame's alternative text (descr); import reads it back. An empty string marks the chart decorative, with the same meaning as an empty Asset alt, but it is a reviewed choice that opf/chart-text-alternative still reports as info (a chart almost always carries a message). When absent, validate accepts text beside the chart instead.",
      "examples": [
        "Revenue grew from $12M in Q1 to $18M in Q2, with the steepest rise in the West region."
      ]
    },
    "colors": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ColorRef"
      },
      "minItems": 1,
      "maxItems": 24,
      "description": "Optional series colors, by position: entry i replaces palette color i, the color of series i (the i-th plotted value column), of slice or category i on a pie, doughnut, treemap or funnel chart, and of the i-th color a histogram, pareto, waterfall or box-and-whisker chart draws with. An entry is any ColorRef: a hex color, a color-scheme slot or role ('accent3', 'secondary') or a 'var:<id>' color variable; a scheme name keeps following the deck if its scheme changes, and is written to PowerPoint as a theme color. Positions past the last entry keep the deck palette (accent1 to accent6, then their tints). A color is kept at 3:1 contrast against the chart panel (a lighter or darker shade is used when it falls short) and 'chart.highlight' wins over it: highlighted marks take the primary color and the rest the muted neutral. A color that cannot be resolved falls back to the palette color for its position. Absent keeps the deck palette exactly.",
      "examples": [
        [
          "accent3",
          "#7B241C"
        ]
      ]
    },
    "highlight": {
      "$ref": "#/$defs/ChartHighlight",
      "description": "Optional emphasis: the series and/or categories that carry the message. The engines draw the highlighted marks in the deck's primary (accent) color and every other mark in a muted neutral derived from the theme (a light grey on a light chart panel, a dim grey on a dark one); there is no color field. A mark is highlighted when its series OR its category is named. Absent keeps today's colors exactly. Supported on column, bar and line charts (series and categories; on a line a category highlight marks that category's points), pie and doughnut charts (categories, one per slice), and area, scatter and radar charts (series); the histogram, pareto, waterfall, funnel, treemap, box-and-whisker, map and combo constructs drop the option with a 'chart-option-adapted' diagnostic, as does a part the type cannot highlight. A name that matches no column or row label is a 'chart-highlight-unknown-name' error."
    }
  }
}