Skip to content

Worksheets

Worksheets turn declared datasource fields into Tableau views. Agents should describe semantic intent here: which fields go on shelves, which mark type to use, which filters/cards are visible, and which analytical overlays belong on the sheet. The compiler owns Tableau's worksheet XML, generated column instances, panes, cards, and mark encodings.

Use spec version 1.0 for new examples. The public schema lives at spec/v1.schema.json.

Worksheet Object

Use one object in worksheets[] for each Tableau worksheet.

{
  "name": "Sales by Category",
  "datasource": "Orders",
  "rows": ["[Orders].[Category]"],
  "cols": [
    {
      "field": "[Orders].[Sales]",
      "aggregation": "sum"
    }
  ],
  "mark": "bar"
}
Field Type Required Values Description
name string Yes Stable worksheet name Referenced by dashboards, actions, stories, and viz-in-tooltip payloads.
datasource string Yes Declared datasource name Primary datasource for field resolution.
secondary_datasources array No Datasource names Enables secondary datasource references for blended or cross-datasource views.
id string No UUID in {...} form Optional stable Tableau sheet ID. Usually omit and let the compiler generate one.
hidden boolean No true, false Hides the worksheet tab while keeping it available to dashboards and tooltips.
rows array No Shelf items Fields, aggregates, date parts, bins, composites, table calcs, or Measure Names/Values pseudo fields on Rows.
cols array No Shelf items Same item shapes as rows, placed on Columns.
pages array No Field refs Adds a Pages shelf. Items are field references, not aggregate objects.
mark string No See mark values Tableau mark class or compiler chart template selector. Defaults are compiler-defined.
map object With map worksheets Map object Defines generated or coordinate map geometry. See Maps.
histogram object With mark: "histogram" Histogram template Chart template configuration. See Chart Templates.
packed_bubble object With mark: "packed_bubble" Packed bubble template Chart template configuration.
box_plot object With mark: "box_plot" Box plot template Chart template configuration.
bullet_graph object With mark: "bullet_graph" Bullet graph template Chart template configuration.
combo object With mark: "combo" Combo template Chart template configuration.
sparkline object With mark: "sparkline" Sparkline template Chart template configuration.
pareto object With mark: "pareto" Pareto template Chart template configuration.
slope object With mark: "slope" Slope chart template Chart template configuration.
population_pyramid object With mark: "population_pyramid" Population pyramid template Chart template configuration.
bump object With mark: "bump" Bump chart template Chart template configuration.
control_chart object With mark: "control_chart" Control chart template Chart template configuration.
waterfall object With mark: "waterfall" Waterfall template Chart template configuration.
donut object With mark: "donut" Donut template Chart template configuration.
candlestick object With mark: "candlestick" Candlestick template Chart template configuration.
filters array No Filter objects Worksheet data filters. See Interactivity.
filter_cards array No Worksheet filter-card objects Shows worksheet-level quick filter cards.
parameter_cards array No Worksheet parameter-card objects Shows worksheet-level parameter controls.
highlighters array No Field refs or aggregates Adds highlighter cards for fields already usable by the worksheet.
encodings object No Mark encodings object Maps fields or aggregates to Color, Size, Label, Tooltip, Path, and other mark channels.
measure_values array No Aggregate shelf items Declares Measure Values entries for KPI tables and multi-measure views.
custom_label object No Mark text object Custom mark label runs.
custom_tooltip object No Tooltip object Custom tooltip runs, including optional viz-in-tooltip sheet payloads.
tooltip_mode string No none Disables worksheet tooltips when set to none.
sorts array No Sort objects Computed or manual member ordering.
totals object No Totals object Row totals, column totals, and subtotals.
reference_lines array No Reference line objects Adds analytics reference lines or percentage bands. See Analytics.
reference_distributions array No Reference distribution objects Adds reference distributions. See Analytics.
forecast object No Forecast object Adds worksheet forecast metadata. See Analytics.
trend_line object No Trend line object Adds worksheet trend line metadata. See Analytics.
formatting array No Style rules Worksheet style rules. See Formatting.
title string No Plain text Worksheet title. Mutually exclusive with title_runs.
title_runs object No Formatted text runs Rich title text with field and parameter tokens. Mutually exclusive with title.
caption string No Plain text Worksheet caption. Mutually exclusive with caption_runs.
caption_runs object No Formatted text runs Rich caption text with field and parameter tokens. Mutually exclusive with caption.
animation object No Animation object Worksheet-level animation settings. See Formatting.
legend_titles array No Legend title objects Overrides generated legend titles.

Mark Values

Value Use
automatic Let Tableau choose the visual mark.
bar, line, area, text, circle, square, shape Primitive worksheet marks.
pie, gantt, treemap, density, multipolygon Primitive marks with channel-specific rules.
histogram, packed_bubble, box_plot, combo, stacked_bar, bullet_graph, sparkline, pareto, slope, population_pyramid, bump, control_chart, waterfall, donut, candlestick Compiler chart-template marks. Most require the matching template object and usually reject user-authored shelves/encodings that would conflict with generated Tableau XML.

Shelf Items

rows[] and cols[] accept several item shapes. Use string field references for dimensions and object forms when the compiler needs extra semantics.

Shape Required Fields Values Description
Field reference String [Datasource].[Field] Places a declared field directly on the shelf.
Aggregate shelf item field, aggregation avg, count, count_distinct, max, min, sum Aggregates a measure or countable field. Optional datasource is allowed for supported secondary datasource cases.
Date part item field, date_part month, quarter, year, month_trunc, week_trunc, year_trunc Emits discrete date parts or continuous date truncs.
Bin item field, bin_size Positive number Creates a generated bin shelf item for a numeric field.
Composite item operator, items operator: cross, nest; items: two or more shelf items Builds cross or nested shelf expressions.
Table calculation item table_calculation See table below Shelf-level quick table calculation.
Pseudo field measure_names or measure_values true Places Measure Names or Measure Values on the shelf.

Aggregate example:

{
  "field": "[Orders].[Sales]",
  "aggregation": "sum"
}

Date and bin examples:

[
  {
    "field": "[Orders].[Order Date]",
    "date_part": "month_trunc"
  },
  {
    "field": "[Orders].[Sales]",
    "bin_size": 100
  }
]

Composite example:

{
  "operator": "nest",
  "items": [
    "[Orders].[Category]",
    "[Orders].[Sub-Category]"
  ]
}

Shelf Table Calculations

Field Type Required Values Description
table_calculation.type string Yes rank, percent_total Quick table calculation kind.
table_calculation.compute_using string Yes table_across, table_down, field Direction or explicit field addressing. field is supported for percent total.
table_calculation.ordering_field string With compute_using: "field" Field reference Field that drives specific-dimension addressing.
table_calculation.source object Yes Aggregate shelf item Source aggregate. rank accepts avg or sum; percent_total accepts avg, count, count_distinct, or sum. 
{
  "table_calculation": {
    "type": "percent_total",
    "compute_using": "table_down",
    "source": {
      "field": "[Orders].[Sales]",
      "aggregation": "sum"
    }
  }
}

Mark Encodings

Encodings map fields or aggregates to the Marks card.

Field Type Values Description
color string, aggregate, Measure Names object, or palette object Field ref, aggregate object, {"measure_names": true}, or color palette object Color marks by a dimension, aggregate measure, or Measure Names.
size string or aggregate Field ref or aggregate object Controls mark size.
text string, aggregate, or Measure Values object Field ref, aggregate object, or {"measure_values": true} Label/text channel.
tooltip string or aggregate Field ref or aggregate object Adds field to generated tooltip.
shape string Field ref Shape encoding field.
path string Field ref Path ordering field, required for flow maps.
wedge_size aggregate Aggregate shelf item Required for primitive pie wedges.
duration aggregate Aggregate shelf item Required for Gantt duration.
tile_size aggregate Aggregate shelf item Required for primitive treemap tile size.
detail array Field refs or rank table-calculation objects Adds Detail marks. 
{
  "encodings": {
    "color": {
      "field": "[Orders].[Segment]",
      "palette": {
        "kind": "categorical",
        "members": [
          {
            "value": "Consumer",
            "color": "#4E79A7"
          },
          {
            "value": "Corporate",
            "color": "#F28E2B"
          }
        ]
      }
    },
    "size": {
      "field": "[Orders].[Quantity]",
      "aggregation": "sum"
    },
    "tooltip": {
      "field": "[Orders].[Profit]",
      "aggregation": "sum"
    },
    "detail": ["[Orders].[Sub-Category]"]
  }
}

Worksheet Cards

Filter Card Object

Field Type Required Values Description
field string Yes Field ref Filtered field already used by a worksheet filter.
date_part string No year, quarter, month Targets a date-part filter card.
mode string No checkdropdown, dropdown, radiolist, slider Tableau quick-filter display mode.
title string No Display text Card title override.

Parameter Card Object

Field Type Required Values Description
parameter string Yes Parameter name Workbook parameter to display.
mode string No compact, slider, type_in Parameter control mode. Defaults to compact.
title string No Display text Card title override.
style object No Parameter card style Allowlisted background/border fields. See Formatting. 
{
  "filter_cards": [
    {
      "field": "[Orders].[Category]",
      "mode": "dropdown",
      "title": "Choose category"
    }
  ],
  "parameter_cards": [
    {
      "parameter": "Sales Target",
      "mode": "slider",
      "title": "Target"
    }
  ]
}

Rich Text And Tooltips

title_runs, caption_runs, custom_label, and custom_tooltip all use run objects. A run must contain exactly one content field: text, field, parameter for worksheet titles/captions, or sheet for tooltip sheets.

Field Type Values Description
runs array One or more run objects Ordered text/token sequence.
show_buttons boolean Tooltip only Controls Tableau tooltip command buttons.
text string Non-empty Literal text run.
field string or shelf item Field ref, aggregate, or date part depending on run type Inserts a field token.
parameter string Title/caption only Inserts a parameter token.
sheet object Tooltip only Viz-in-tooltip payload.
font_name string Non-empty Run font family.
font_size integer >= 1 Run font size.
font_color string #RRGGBB Run text color.
font_alignment string left Text alignment supported by the current schema.
bold, italic, underline boolean true, false Text emphasis flags.

Tooltip sheet object:

Field Type Required Values Description
worksheet string Yes Worksheet name Hidden or visible worksheet to embed.
fields array Yes Field refs Fields used to filter the tooltip sheet.
max_width integer No >= 1 Viz-in-tooltip maximum width.
max_height integer No >= 1 Viz-in-tooltip maximum height.
filter string No all_fields Tableau filter behavior. 
{
  "title_runs": {
    "runs": [
      {
        "text": "Sales by "
      },
      {
        "field": "[Orders].[Category]"
      },
      {
        "text": " against "
      },
      {
        "parameter": "Sales Target"
      }
    ]
  },
  "custom_tooltip": {
    "show_buttons": false,
    "runs": [
      {
        "text": "Profit: ",
        "bold": true
      },
      {
        "field": "[Orders].[Profit]"
      },
      {
        "sheet": {
          "worksheet": "Tooltip Detail",
          "fields": ["[Orders].[Category]"],
          "max_width": 300,
          "max_height": 180,
          "filter": "all_fields"
        }
      }
    ]
  }
}

Sorts And Totals

Sort object:

Field Type Required Values Description
kind string No computed, manual Defaults to computed.
field string Yes Field ref Field whose members are sorted.
by string Computed only Field ref Field/measure to sort by.
direction string Yes asc, desc Sort direction.
values array Manual only strings, numbers, booleans Exact member order for manual sorts.

Totals object:

Field Type Required Values Description
rows_total boolean At least one totals field true, false Shows row grand totals when true.
cols_total boolean At least one totals field true, false Shows column grand totals when true.
subtotals array At least one totals field Subtotal shelf refs Enables subtotals for listed shelf fields. 
{
  "sorts": [
    {
      "kind": "computed",
      "field": "[Orders].[Category]",
      "by": "[Orders].[Sales]",
      "direction": "desc"
    },
    {
      "kind": "manual",
      "field": "[Orders].[Segment]",
      "direction": "asc",
      "values": ["Consumer", "Corporate", "Home Office"]
    }
  ],
  "totals": {
    "rows_total": true,
    "cols_total": true,
    "subtotals": ["[Orders].[Category]"]
  }
}

Measure Names And Measure Values

Use Measure Names and Measure Values for KPI tables and multi-measure views.

{
  "name": "KPI Table",
  "datasource": "Orders",
  "measure_values": [
    {
      "field": "[Orders].[Sales]",
      "aggregation": "sum"
    },
    {
      "field": "[Orders].[Profit]",
      "aggregation": "sum"
    },
    {
      "field": "[Orders].[Quantity]",
      "aggregation": "sum"
    }
  ],
  "rows": [
    {
      "measure_names": true
    }
  ],
  "mark": "text",
  "encodings": {
    "text": {
      "measure_values": true
    },
    "color": {
      "measure_names": true,
      "palette": {
        "kind": "categorical",
        "members": [
          {
            "measure": {
              "field": "[Orders].[Sales]",
              "aggregation": "sum"
            },
            "color": "#4E79A7"
          },
          {
            "measure": {
              "field": "[Orders].[Profit]",
              "aggregation": "sum"
            },
            "color": "#E15759"
          }
        ]
      }
    }
  }
}

Pages And Highlighters

{
  "name": "Regional Sales Pages",
  "datasource": "Orders",
  "pages": ["[Orders].[Region]"],
  "highlighters": [
    "[Orders].[Category]",
    {
      "field": "[Orders].[Sales]",
      "aggregation": "sum"
    }
  ],
  "rows": ["[Orders].[Category]"],
  "cols": [
    {
      "field": "[Orders].[Sales]",
      "aggregation": "sum"
    }
  ],
  "mark": "bar"
}