Configuration JSON¶

The compiler config is a workbook description. It names datasources, declares semantic fields, describes worksheets and dashboards, and lets the compiler own the Tableau XML details.

This section is organized like component documentation. Each page covers one feature family, defines the available JSON fields and values, then gives copyable examples and validation notes.

Top-Level Shape¶

Every workbook starts with the same broad object:

{
  "version": "1.0",
  "target": {
    "tableau_version": "26.1",
    "source_build": "2026.1.2 (20261.26.0512.1636)",
    "source_platform": "mac"
  },
  "package": {
    "assets": []
  },
  "parameters": [],
  "datasources": [],
  "worksheets": [],
  "dashboards": [],
  "actions": []
}

Use spec version 1.0 when authoring new configs. The public schema lives at spec/v1.schema.json.

Minimal Workbook¶

This is the smallest useful authoring shape: one datasource, one worksheet, and one bar view.

{
  "version": "1.0",
  "target": {
    "tableau_version": "26.1"
  },
  "datasources": [
    {
      "name": "Orders",
      "caption": "Orders",
      "columns": [
        {
          "name": "Category",
          "role": "dimension",
          "type": "nominal",
          "datatype": "string"
        },
        {
          "name": "Sales",
          "role": "measure",
          "type": "quantitative",
          "datatype": "real"
        }
      ]
    }
  ],
  "worksheets": [
    {
      "name": "Sales by Category",
      "datasource": "Orders",
      "rows": ["[Orders].[Category]"],
      "cols": [
        {
          "field": "[Orders].[Sales]",
          "aggregation": "sum"
        }
      ],
      "mark": "bar"
    }
  ]
}

Packaged Workbook¶

Most useful workbooks package a local CSV or Excel asset. The package.assets entry names the source file in the fixture or project tree and the member path inside the .twbx. The datasource connection then points at that member.

{
  "version": "1.0",
  "package": {
    "assets": [
      {
        "source": "assets/orders.csv",
        "member": "Data/orders.csv"
      }
    ]
  },
  "datasources": [
    {
      "name": "Orders",
      "connection": {
        "kind": "local_file",
        "format": "csv",
        "asset": "Data/orders.csv"
      },
      "columns": [
        {
          "name": "Region",
          "role": "dimension",
          "type": "nominal",
          "datatype": "string"
        },
        {
          "name": "Sales",
          "role": "measure",
          "type": "quantitative",
          "datatype": "real"
        }
      ]
    }
  ],
  "worksheets": [
    {
      "name": "Regional Sales",
      "datasource": "Orders",
      "rows": ["[Orders].[Region]"],
      "cols": [
        {
          "field": "[Orders].[Sales]",
          "aggregation": "sum"
        }
      ],
      "mark": "bar"
    }
  ]
}

Feature Pages¶

Page	Examples
Datasources	CSV, Excel, relationships, columns, metadata, datasource filters, parameters.
Worksheets	Shelves, marks, encodings, filters, titles, captions, Measure Names and Measure Values.
Chart Templates	Primitive charts, pie, combo, sparkline, bullet, Pareto, and other high-level templates.
Dashboards	Tiled dashboards, nested containers, controls, legends, text, image, web, and navigation objects.
Interactivity	Filter, highlight, parameter, URL, and go-to-sheet actions.
Formatting	Rich text, worksheet formatting, dashboard zone styles, legends, quick filters, and themes.
Maps	Filled maps, symbol maps, coordinate point maps, density maps, and flow maps.
Analytics	Calculations, LODs, table calculations, forecasts, reference lines, bands, distributions, trend lines.
Packaging And Validation	`.twb`, `.twbx`, schema validation, fixture manifests, Tier 3 proof.

Authoring Rules¶

Rule	Why
Use stable object names	Names become dependencies for shelves, dashboards, actions, controls, and generated XML references.
Declare fields before using them	Shelves, filters, calculations, encodings, and relationships all resolve against declared columns.
Prefer semantic objects over Tableau XML names	Write `{ "field": "[Orders].[Sales]", "aggregation": "sum" }`, not generated `usr:` or `none:` instances.
Keep Superstore generic	Superstore proves coverage, but examples should work for any Orders-like dataset.
Add Desktop proof for risky XML	Datasources, layout, actions, formatting, maps, and generated Tableau instances can pass XSD and still fail in Desktop.