OPF
OpenPresentation/opf
SpecAuthoring schema referenceView source

Chart Type

Schema for chart-type records: display metadata for chart pickers (name, group, expected series, complexity) and the Open XML mapping a picker can describe. One record per chart type that Aspose.Slides officially supports (see mappings.renderers["aspose-slides"].chartType), plus the column-and-line combination 'combo'. A document's chart.type is an engine vocabulary validated directly; engines never look a chart-type record up. pptx.gallery publishes these records and @openpresentation/gallery ships them as catalogDisplay.chartTypes.

Schema $id
https://openpresentation.org/schema/opf-chart-type/v1
Type
object
Source
spec/schemas/chart-type.schema.json
Fields
12 · 4 required

Field index

FieldTypeReq.DefaultDescription
$schemaconstyes—Identifies this record as a chart type in the open presentation catalog.
$schema · Allowed values
"https://openpresentation.org/schema/opf-chart-type/v1"
idstringyes—The chart-type value (chart.type) this record describes. Lowercase kebab-case; it may start with a digit (e.g., '100pct-stacked-column') to mirror conventional chart naming.
namestringyes—Human-readable name of the chart type, as a chart picker shows it.
summarystring——One-sentence positioning: when to reach for this chart variant.
descriptionstring——Longer prose describing the chart and ideal use cases.
mappingsref:ChartTypeMappingsyes—Canonical and optional renderer-specific mappings used by engines to render this chart type.
groupstring——Top-level grouping in the chart picker.
groupSortinteger——Display ordering hint within the chart group.
complexityenum——Shape of the underlying data: a flat series ('simple'), one with engine-side calculation ('calculated'), parent-child rows ('hierarchical'), or pre-normalized rows ('normalized'). The editor offers only 'simple' types as switch targets for a chart's existing data.
complexity · Allowed values
"simple""calculated""hierarchical""normalized"
seriesinteger——Number of data series this chart type expects: exactly that many, except that a stacked or percent-stacked type and a combination (composition 'mixed', such as combo) expect at least that many. The editor offers a type that expects more than one series only for data with a fitting number of value columns; a one-series type fits one value column, and column, bar, line, area and radar types fit any number.
tagsarray<string>——Free-form labels for filtering and search.
previewobject——Visual previews of the record, used by picker UIs and inline rendering. All sub-fields are optional; engines fall back gracefully when previews aren't available.

$schema

typeconstrequiredyesdefault—

Identifies this record as a chart type in the open presentation catalog.

$schema · Allowed values
"https://openpresentation.org/schema/opf-chart-type/v1"
$schema.json
{
  "$schema": "https://openpresentation.org/schema/opf-chart-type/v1"
}

id

typestringrequiredyesdefault—pattern^[a-z0-9][a-z0-9-]*$

The chart-type value (chart.type) this record describes. Lowercase kebab-case; it may start with a digit (e.g., '100pct-stacked-column') to mirror conventional chart naming.

id.json
{
  "id": "column"
}

name

typestringrequiredyesdefault—

Human-readable name of the chart type, as a chart picker shows it.

name.json
{
  "name": "Column"
}

summary

typestringrequirednodefault—

One-sentence positioning: when to reach for this chart variant.

summary.json
{
  "summary": "Single-series vertical column chart for comparing values across categories."
}

description

typestringrequirednodefault—

Longer prose describing the chart and ideal use cases.

description.json
{
  "description": "Use a stacked column when you want to compare totals across categories and also show how each series contributes — e.g., revenue by quarter split by product line. Best with 2–4 series and ≤12 categories."
}

mappings

typeref:ChartTypeMappingsrequiredyesdefault—

Canonical and optional renderer-specific mappings used by engines to render this chart type.

mappings.openxml.barDir · Allowed values
"bar""col"
mappings.openxml.grouping · Allowed values
"standard""clustered""stacked""percentStacked"
mappings.openxml.radarStyle · Allowed values
"standard""marker""filled"
mappings.openxml.scatterStyle · Allowed values
"line""lineMarker""marker""smooth""smoothMarker"
mappings.openxml.composition · Allowed values
"single""mixed""extension"

group

typestringrequirednodefault—

Top-level grouping in the chart picker.

group.json
{
  "group": "Column"
}

groupSort

typeintegerrequirednodefault—

Display ordering hint within the chart group.

groupSort.json
{
  "groupSort": 1
}

complexity

typeenumrequirednodefault—

Shape of the underlying data: a flat series ('simple'), one with engine-side calculation ('calculated'), parent-child rows ('hierarchical'), or pre-normalized rows ('normalized'). The editor offers only 'simple' types as switch targets for a chart's existing data.

complexity · Allowed values
"simple""calculated""hierarchical""normalized"
complexity.json
{
  "complexity": "simple"
}

series

typeintegerrequirednodefault—

Number of data series this chart type expects: exactly that many, except that a stacked or percent-stacked type and a combination (composition 'mixed', such as combo) expect at least that many. The editor offers a type that expects more than one series only for data with a fitting number of value columns; a one-series type fits one value column, and column, bar, line, area and radar types fit any number.

series.json
{
  "series": 1
}

tags

typearray<string>requirednodefault—

Free-form labels for filtering and search.

tags.json
{
  "tags": [
    "column",
    "comparison"
  ]
}

preview

typeobjectrequirednodefault—

Visual previews of the record, used by picker UIs and inline rendering. All sub-fields are optional; engines fall back gracefully when previews aren't available.

Complete definition constraints
Schema constraints
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://openpresentation.org/schema/opf-chart-type/v1",
  "$comment": "The v1 in the $id is the pre-1.0 line, not a frozen contract: this schema may change in any 0.x minor release. The release that produced this copy is the version of the @openpresentation/opf package it came from (opf --version; opf schemas lists it next to each id). See docs/schema-versioning.md.",
  "title": "Chart Type",
  "description": "Schema for chart-type records: display metadata for chart pickers (name, group, expected series, complexity) and the Open XML mapping a picker can describe. One record per chart type that Aspose.Slides officially supports (see mappings.renderers[\"aspose-slides\"].chartType), plus the column-and-line combination 'combo'. A document's chart.type is an engine vocabulary validated directly; engines never look a chart-type record up. pptx.gallery publishes these records and @openpresentation/gallery ships them as catalogDisplay.chartTypes.",
  "type": "object",
  "additionalProperties": false,
  "patternProperties": {
    "^x-": {
      "description": "Publisher extension member, such as the `x-gallery` presentation metadata that pptx.gallery adds to the records it publishes. Engines and validators ignore top-level `x-*` members, and the pinned snapshot in @openpresentation/gallery never carries them."
    }
  },
  "required": [
    "$schema",
    "id",
    "name",
    "mappings"
  ],
  "properties": {
    "$schema": {
      "type": "string",
      "const": "https://openpresentation.org/schema/opf-chart-type/v1",
      "description": "Identifies this record as a chart type in the open presentation catalog."
    },
    "id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9-]*$",
      "description": "The chart-type value (`chart.type`) this record describes. Lowercase kebab-case; it may start with a digit (e.g., '100pct-stacked-column') to mirror conventional chart naming.",
      "examples": [
        "column",
        "bar",
        "stacked-column",
        "doughnut",
        "treemap",
        "100pct-stacked-column"
      ]
    },
    "name": {
      "type": "string",
      "description": "Human-readable name of the chart type, as a chart picker shows it.",
      "examples": [
        "Column",
        "Stacked Column",
        "Doughnut",
        "Treemap"
      ]
    },
    "summary": {
      "type": "string",
      "description": "One-sentence positioning: when to reach for this chart variant.",
      "examples": [
        "Single-series vertical column chart for comparing values across categories.",
        "Stacked column chart that shows how the parts of each category add up to its total."
      ]
    },
    "description": {
      "type": "string",
      "description": "Longer prose describing the chart and ideal use cases.",
      "examples": [
        "Use a stacked column when you want to compare totals across categories and also show how each series contributes — e.g., revenue by quarter split by product line. Best with 2–4 series and ≤12 categories."
      ]
    },
    "mappings": {
      "$ref": "#/$defs/ChartTypeMappings",
      "description": "Canonical and optional renderer-specific mappings used by engines to render this chart type."
    },
    "group": {
      "type": "string",
      "description": "Top-level grouping in the chart picker.",
      "examples": [
        "Column",
        "Bar",
        "Line",
        "Area",
        "Pie",
        "Radar",
        "Histogram",
        "XY (Scatter)",
        "Treemap",
        "Map",
        "Combo",
        "Other"
      ]
    },
    "groupSort": {
      "type": "integer",
      "minimum": 0,
      "description": "Display ordering hint within the chart group.",
      "examples": [
        1,
        2,
        10
      ]
    },
    "complexity": {
      "type": "string",
      "enum": [
        "simple",
        "calculated",
        "hierarchical",
        "normalized"
      ],
      "description": "Shape of the underlying data: a flat series ('simple'), one with engine-side calculation ('calculated'), parent-child rows ('hierarchical'), or pre-normalized rows ('normalized'). The editor offers only 'simple' types as switch targets for a chart's existing data."
    },
    "series": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of data series this chart type expects: exactly that many, except that a stacked or percent-stacked type and a combination (composition 'mixed', such as combo) expect at least that many. The editor offers a type that expects more than one series only for data with a fitting number of value columns; a one-series type fits one value column, and column, bar, line, area and radar types fit any number.",
      "examples": [
        1,
        2,
        3
      ]
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Free-form labels for filtering and search.",
      "examples": [
        [
          "column",
          "comparison"
        ],
        [
          "stacked",
          "composition"
        ]
      ]
    },
    "preview": {
      "type": "object",
      "description": "Visual previews of the record, used by picker UIs and inline rendering. All sub-fields are optional; engines fall back gracefully when previews aren't available.",
      "properties": {
        "src": {
          "type": "string",
          "format": "uri",
          "description": "Main preview image (PNG/JPG). Used as the primary visual in picker UIs and previews of the record.",
          "examples": [
            "https://www.pptx.gallery/chart-types/column.png"
          ]
        },
        "thumbnailSrc": {
          "type": "string",
          "format": "uri",
          "description": "Smaller thumbnail preview suited to dense grid views.",
          "examples": [
            "https://www.pptx.gallery/chart-types/column.thumbnail.png"
          ]
        },
        "vectorSrc": {
          "type": "string",
          "format": "uri",
          "description": "SVG / vector preview for crisp scaling at any size.",
          "examples": [
            "https://www.pptx.gallery/chart-types/column.svg"
          ]
        }
      }
    }
  },
  "$defs": {
    "ChartTypeMappings": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "openxml"
      ],
      "properties": {
        "openxml": {
          "$ref": "#/$defs/OpenXmlChartMapping",
          "description": "Canonical mapping to Open XML chart structures."
        },
        "renderers": {
          "type": "object",
          "description": "Optional renderer-specific mappings. Keys are renderer ids; values are intentionally opaque to OPF. The bundled catalog records the matching Aspose.Slides ChartType enumeration member under the \"aspose-slides\" key, e.g. {\"aspose-slides\": {\"chartType\": \"StackedColumn\"}}; a mixed composition names the ChartType it starts from and the series type it switches series to, e.g. {\"chartType\": \"ClusteredColumn\", \"lineSeriesType\": \"LineWithMarkers\"}.",
          "additionalProperties": {
            "type": "object",
            "additionalProperties": true
          },
          "examples": [
            {
              "aspose-slides": {
                "chartType": "ClusteredColumn"
              }
            }
          ]
        }
      }
    },
    "OpenXmlChartMapping": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "element": {
          "type": "string",
          "description": "Primary Open XML chart element or extension chart element, such as 'barChart', 'lineChart', 'pieChart', 'treemapChart', or 'waterfallChart'.",
          "examples": [
            "barChart",
            "lineChart",
            "pieChart"
          ]
        },
        "barDir": {
          "type": "string",
          "enum": [
            "bar",
            "col"
          ],
          "description": "Bar direction for Open XML barChart mappings."
        },
        "grouping": {
          "type": "string",
          "enum": [
            "standard",
            "clustered",
            "stacked",
            "percentStacked"
          ],
          "description": "Open XML chart grouping value when the chart family supports grouping."
        },
        "marker": {
          "type": "boolean",
          "description": "Whether the chart type expects visible data markers."
        },
        "radarStyle": {
          "type": "string",
          "enum": [
            "standard",
            "marker",
            "filled"
          ],
          "description": "Open XML radarStyle value for radarChart mappings."
        },
        "scatterStyle": {
          "type": "string",
          "enum": [
            "line",
            "lineMarker",
            "marker",
            "smooth",
            "smoothMarker"
          ],
          "description": "Open XML scatterStyle value for scatterChart mappings."
        },
        "composition": {
          "type": "string",
          "enum": [
            "single",
            "mixed",
            "extension"
          ],
          "description": "Whether the chart maps to one standard chart element, multiple combined chart elements, or an Open XML extension chart."
        },
        "extension": {
          "type": "string",
          "description": "Optional Open XML extension namespace or element hint for extension charts.",
          "examples": [
            "cx:treemapChart",
            "cx:waterfallChart"
          ]
        },
        "series": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/OpenXmlChartMapping"
          },
          "description": "Open XML chart elements used by mixed/composite chart types."
        },
        "notes": {
          "type": "string",
          "description": "Short implementation note for mappings that need renderer interpretation."
        }
      }
    }
  }
}

Definition choices

Values declared by this schema and its nested definitions. Paths ending in [] describe array items; * describes each dictionary entry. Variant paths apply within the named schema branch.

$defs.OpenXmlChartMapping.barDir · Allowed values
"bar""col"
$defs.OpenXmlChartMapping.grouping · Allowed values
"standard""clustered""stacked""percentStacked"
$defs.OpenXmlChartMapping.radarStyle · Allowed values
"standard""marker""filled"
$defs.OpenXmlChartMapping.scatterStyle · Allowed values
"line""lineMarker""marker""smooth""smoothMarker"
$defs.OpenXmlChartMapping.composition · Allowed values
"single""mixed""extension"