SpecDefinition referenceView source

Table

Table content, inline or dataset-backed. An inline table has 'rows' (required) and optional 'columns'. A dataset-backed table has 'dataset' (required) and optional 'fields', and no 'rows' or 'columns': it takes its headers, rows and column formats from the dataset (per-cell styles need an inline table).

Metadata

Definition: #/$defs/Table
Form: object
Source: spec/schemas/opf.schema.json

Field index

Field	Type	Req.	Description
columns	array<string \| array<ref:TextRun> \| ref:StyledTableCell \| ref:DataColumn \| null>	—	Optional column labels. Labels may be strings, rich runs, styled cell objects or DataColumn objects ({ "name", "format" }). A header's 'format' (DataColumn or StyledTableCell) is the column's number format; a body cell's own format wins. Null is an empty label or a placeholder covered by a preceding column span.
rows	array<array<ref:TableCell>>	—	Two-dimensional table row data; each row aligns by index with columns when columns are supplied.
dataset	ref:DatasetId	—	Id of a top-level dataset that supplies this table's headers, rows and column formats. Excludes 'rows' and 'columns'. An unknown id is a 'dataset-unknown' error.
fields	ref:DatasetFields	—	Dataset tables only: the dataset columns to show, by name and in order. Absent shows every column. An unknown name is a 'dataset-field-unknown' error.
alt	string	—	Text alternative for the table: what it shows (the point and the key numbers), not 'a table'. The preview exposes it as the table's accessible name (role group with aria-label; the cells stay readable) and the PowerPoint export writes it as the table frame's alternative text (descr); import reads it back. An empty string hides a purely decorative table, with the same meaning as an empty Asset alt. The alt is a summary read before the cells, which stay readable, so it is most useful for a large or dense table; validate does not require one and does not report a missing one.

`columns`

typearray<string | array<ref:TextRun> | ref:StyledTableCell | ref:DataColumn | null>requirednodefault—

Optional column labels. Labels may be strings, rich runs, styled cell objects or DataColumn objects ({ "name", "format" }). A header's 'format' (DataColumn or StyledTableCell) is the column's number format; a body cell's own format wins. Null is an empty label or a placeholder covered by a preceding column span.

columns[] (oneOf 3).style.fill · Named choices (see schema for other values and constraints): "accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"
columns[] (oneOf 3).style.color · Named choices (see schema for other values and constraints): "accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"
columns[] (oneOf 3).style.align · Allowed values: "left", "center", "right"
columns[] (oneOf 3).style.verticalAlign · Allowed values: "top", "middle", "bottom"
columns[] (oneOf 3).style.borders.top.color · Named choices (see schema for other values and constraints): "accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"
columns[] (oneOf 3).style.borders.top.dash · Allowed values: "solid", "dash", "dot"

columns.json

{
  "columns": [
    "Region",
    "Q3 Revenue",
    "Q4 Revenue",
    "YoY %"
  ]
}

`rows`

typearray<array<ref:TableCell>>requirednodefault—

Two-dimensional table row data; each row aligns by index with columns when columns are supplied.

rows[][] (oneOf 2).style.fill · Named choices (see schema for other values and constraints): "accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"
rows[][] (oneOf 2).style.color · Named choices (see schema for other values and constraints): "accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"
rows[][] (oneOf 2).style.align · Allowed values: "left", "center", "right"
rows[][] (oneOf 2).style.verticalAlign · Allowed values: "top", "middle", "bottom"
rows[][] (oneOf 2).style.borders.top.color · Named choices (see schema for other values and constraints): "accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink", "primary", "secondary", "accent", "background", "surface", "surfaceAlt", "text", "textSecondary"
rows[][] (oneOf 2).style.borders.top.dash · Allowed values: "solid", "dash", "dot"

rows.json

{
  "rows": [
    [
      "North America",
      12.4,
      18.1,
      "46%"
    ],
    [
      "EMEA",
      8.2,
      11.5,
      "40%"
    ]
  ]
}

`dataset`

typeref:DatasetIdrequirednodefault—

Id of a top-level dataset that supplies this table's headers, rows and column formats. Excludes 'rows' and 'columns'. An unknown id is a 'dataset-unknown' error.

`fields`

typeref:DatasetFieldsrequirednodefault—

Dataset tables only: the dataset columns to show, by name and in order. Absent shows every column. An unknown name is a 'dataset-field-unknown' error.

`alt`

typestringrequirednodefault—

Text alternative for the table: what it shows (the point and the key numbers), not 'a table'. The preview exposes it as the table's accessible name (role group with aria-label; the cells stay readable) and the PowerPoint export writes it as the table frame's alternative text (descr); import reads it back. An empty string hides a purely decorative table, with the same meaning as an empty Asset alt. The alt is a summary read before the cells, which stay readable, so it is most useful for a large or dense table; validate does not require one and does not report a missing one.

alt.json

{
  "alt": "North America grew 46% to $18.1M in Q4, ahead of EMEA at 40%."
}

Complete definition constraints

Schema constraints

{
  "type": "object",
  "description": "Table content, inline or dataset-backed. An inline table has 'rows' (required) and optional 'columns'. A dataset-backed table has 'dataset' (required) and optional 'fields', and no 'rows' or 'columns': it takes its headers, rows and column formats from the dataset (per-cell styles need an inline table).",
  "additionalProperties": false,
  "if": {
    "required": [
      "dataset"
    ]
  },
  "then": {
    "properties": {
      "rows": false,
      "columns": false
    }
  },
  "else": {
    "required": [
      "rows"
    ],
    "properties": {
      "fields": false
    }
  },
  "properties": {
    "columns": {
      "type": "array",
      "items": {
        "oneOf": [
          {
            "type": "string"
          },
          {
            "type": "array",
            "items": {
              "$ref": "#/$defs/TextRun"
            }
          },
          {
            "$ref": "#/$defs/StyledTableCell"
          },
          {
            "$ref": "#/$defs/DataColumn"
          },
          {
            "type": "null"
          }
        ]
      },
      "description": "Optional column labels. Labels may be strings, rich runs, styled cell objects or DataColumn objects ({ \"name\", \"format\" }). A header's 'format' (DataColumn or StyledTableCell) is the column's number format; a body cell's own format wins. Null is an empty label or a placeholder covered by a preceding column span.",
      "examples": [
        [
          "Region",
          "Q3 Revenue",
          "Q4 Revenue",
          "YoY %"
        ]
      ]
    },
    "rows": {
      "type": "array",
      "items": {
        "type": "array",
        "items": {
          "$ref": "#/$defs/TableCell"
        }
      },
      "description": "Two-dimensional table row data; each row aligns by index with columns when columns are supplied.",
      "examples": [
        [
          [
            "North America",
            12.4,
            18.1,
            "46%"
          ],
          [
            "EMEA",
            8.2,
            11.5,
            "40%"
          ]
        ]
      ]
    },
    "dataset": {
      "$ref": "#/$defs/DatasetId",
      "description": "Id of a top-level dataset that supplies this table's headers, rows and column formats. Excludes 'rows' and 'columns'. An unknown id is a 'dataset-unknown' error."
    },
    "fields": {
      "$ref": "#/$defs/DatasetFields",
      "description": "Dataset tables only: the dataset columns to show, by name and in order. Absent shows every column. An unknown name is a 'dataset-field-unknown' error."
    },
    "alt": {
      "type": "string",
      "description": "Text alternative for the table: what it shows (the point and the key numbers), not 'a table'. The preview exposes it as the table's accessible name (role group with aria-label; the cells stay readable) and the PowerPoint export writes it as the table frame's alternative text (descr); import reads it back. An empty string hides a purely decorative table, with the same meaning as an empty Asset alt. The alt is a summary read before the cells, which stay readable, so it is most useful for a large or dense table; validate does not require one and does not report a missing one.",
      "examples": [
        "North America grew 46% to $18.1M in Q4, ahead of EMEA at 40%."
      ]
    }
  }
}