Skip to content

Packaging And Validation

The compiler produces deterministic .twb and .twbx artifacts. Packaging and validation are part of the feature contract: a feature is not accepted just because JSON validates. Semantically risky Tableau XML also needs fixtures, negative validation, and Desktop proof.

Top-Level Workbook Object

Field Type Required Values Description
version string Yes 1.0 Public JSON spec version. New configs should use 1.0.
target object No Target object Tableau target metadata.
package object No Package object Files to include in .twbx output. Required for local CSV/Excel datasource assets and dashboard image/theme assets.
workbook_theme object No Custom theme object Packaged workbook theme JSON.
animation object No Animation object Workbook-level animation defaults.
parameters array No Parameter objects Workbook parameters. See Datasources.
datasources array Yes Datasource objects Declared workbook datasources.
datasource_relationships array No Cross-datasource relationships Workbook-level relationship metadata between datasources.
worksheets array Yes Worksheet objects Workbook worksheets.
dashboards array No Dashboard objects Workbook dashboards.
actions array No Dashboard action objects Interactivity actions.
stories array No Story objects Tableau stories. 
{
  "version": "1.0",
  "target": {
    "tableau_version": "26.1",
    "source_build": "2026.1.2 (20261.26.0512.1636)",
    "source_platform": "mac"
  },
  "package": {
    "assets": [
      {
        "source": "assets/orders.csv",
        "member": "Data/orders.csv"
      }
    ]
  },
  "datasources": [],
  "worksheets": []
}

Package Object

package.assets[] declares files to copy into a .twbx. The compiled workbook XML is written as workbook.twb by default. If a different workbook archive member is needed, use the CLI flag --workbook-member-name; it is not a JSON config field.

Field Type Required Values Description
assets array Yes Package asset objects Files to include in .twbx.

Package Asset Object

Field Type Required Values Description
source string Yes Local path relative to the input JSON File on disk to package.
member string Yes POSIX archive path Path inside the .twbx. Datasource connection.asset, image asset, and theme member values refer to this path. 
{
  "package": {
    "assets": [
      {
        "source": "assets/orders.csv",
        "member": "Data/orders.csv"
      },
      {
        "source": "assets/sales_model.xlsx",
        "member": "Data/sales_model.xlsx"
      },
      {
        "source": "assets/logo.png",
        "member": "Images/logo.png"
      },
      {
        "source": "assets/theme.json",
        "member": "theme.json"
      }
    ]
  }
}

Target Object

Field Type Required Values Description
tableau_version string No 26.1 Current compiler target.
source_build string No Non-empty string Tableau source build metadata. Defaults to the compiler's Desktop 2026.1 build.
source_platform string No mac, win Source platform metadata. 
{
  "target": {
    "tableau_version": "26.1",
    "source_build": "2026.1.2 (20261.26.0512.1636)",
    "source_platform": "mac"
  }
}

Story Object

Stories are top-level workbook objects that point at worksheets or dashboards.

Field Type Required Values Description
name string Yes Stable story name Story sheet name.
id string No UUID in {...} form Optional stable Tableau story ID. Usually omit.
width integer No >= 1, default 800 Story width.
height integer No >= 1, default 600 Story height.
nav_type string No arrowonly, caption, dot, number Story navigation type. Defaults to caption.
show_nav_arrows boolean No true, false Whether story navigation arrows are visible. Defaults to true.
points array Yes Story point objects Ordered story points.

Story point object:

Field Type Required Values Description
target string Yes Worksheet or dashboard name Sheet shown by the story point.
caption string No Display text Story point caption. 
{
  "stories": [
    {
      "name": "Quarterly Story",
      "width": 1000,
      "height": 700,
      "nav_type": "caption",
      "show_nav_arrows": true,
      "points": [
        {
          "target": "Executive Overview",
          "caption": "Overview"
        },
        {
          "target": "Sales Detail",
          "caption": "Sales detail"
        }
      ]
    }
  ]
}

Compile Commands

Use uv for all Python commands.

uv sync --all-groups
uv run twbc validate-spec tests/fixtures/workbooks/single_sheet_basic/input.json
uv run twbc compile tests/fixtures/workbooks/single_sheet_basic/input.json \
  -o /tmp/single_sheet_basic.twb \
  --validate
uv run twbc compile tests/fixtures/workbooks/single_sheet_basic/input.json \
  -o /tmp/single_sheet_basic.twbx \
  --twbx \
  --validate
uv run twbc validate /tmp/single_sheet_basic.twb
uv run twbc schema-audit

Zensical Docs Commands

uv sync --all-groups
uv run zensical serve
uv run zensical build --clean

Fixture Layout

Each fixture should be self-explanatory to an agent and should carry both positive and negative evidence when the feature needs validation guards.

tests/fixtures/workbooks/my_feature/
  input.json
  expected.twb
  expected.twbx.manifest.json
  expectation.md
  coverage.json
  assets/
    orders.csv
File Required Description
input.json Yes Source config for the fixture.
expected.twb Positive fixtures Golden workbook XML.
expected.twbx.manifest.json Packaged fixtures Deterministic archive manifest.
expectation.md Yes Human-readable intent, expected XML behavior, and risk notes.
coverage.json Yes Feature coverage manifest.
assets/ When files are packaged Local CSV, Excel, image, or theme assets used by package.assets.

Coverage Manifest

{
  "features": [
    "dashboard",
    "worksheet_aggregate_shelves",
    "local_csv_datasource",
    "packaged_assets",
    "deterministic_xml",
    "deterministic_twbx"
  ],
  "failure_modes": ["FM-01", "FM-03", "FM-07"],
  "xsd_skip_sites": [],
  "tier3": "smoke"
}
Field Type Values Description
features array Stable feature IDs Machine-readable coverage tags.
failure_modes array Failure-mode IDs Validation risks covered by the fixture.
xsd_skip_sites array Skip-site IDs XML regions intentionally outside XSD validation. Keep empty unless the fixture exercises a known skip site.
tier3 string smoke, nightly, or project-defined tier Desktop proof tier selector.

Tier 3 Desktop Evidence

Tier 3 prepares .twbx artifacts and evidence manifests for Tableau Desktop round-trip checks.

uv run twbc tier3-init-run \
  --fixtures-root tests/fixtures/workbooks \
  --tier3 smoke \
  --tier3 nightly \
  -o /tmp/twbc-tier3-run

After Desktop automation or manual review, record each result:

uv run twbc tier3-record \
  /tmp/twbc-tier3-run/run.json \
  my_feature \
  --status pass \
  --opened \
  --desktop-version "Tableau Desktop 2026.1" \
  --note "Opened cleanly; no repair dialog."

Validation Layers

Layer Command or test Catches
JSON schema and semantic validation uv run twbc validate-spec input.json Invalid config shape, missing references, unsupported combinations.
Compile and XSD validation uv run twbc compile input.json -o out.twb --validate Invalid workbook XML structure.
TWBX packaging uv run twbc compile input.json -o out.twbx --twbx --validate Missing package assets and invalid packaged workbook member XML.
Fixture sweep uv run pytest tests/test_fixture_sweep.py Golden drift, missing assets, negative fixture behavior.
Skip-site policy uv run pytest tests/test_xsd_skip_sites.py Unsupported XML extension surfaces.
Tier 3 artifacts uv run twbc tier3-init-run ... Desktop evidence run directory and .twbx artifacts.
Tableau Desktop proof tier3-record plus screenshots/logs Tableau load, repair, render, or interaction failures.

When To Require Desktop Proof

Require Desktop proof when the feature touches semantic Tableau XML that XSD cannot fully prove.

Feature surface Why proof matters
Datasource connections, relationships, and metadata records XSD does not prove Tableau can connect, infer metadata, or use logical relationships correctly.
Calculations, LODs, table calculations, generated bins, and z-scores Generated Tableau column instances can be structurally valid but semantically wrong.
Maps and geography Tableau can load a workbook with blank or ambiguous maps.
Dashboard layout, floating zones, controls, legends, images, web pages, and buttons Layout drift can be visual rather than structural.
Actions and Viz-in-Tooltip Interaction semantics are stored across multiple workbook regions.
Formatting allowlists and zone styles Style XML often lives near XSD skip sites and can silently render differently.
Packaging Missing or mismatched package members can produce a valid .twbx archive that Tableau cannot use as intended.

Desktop evidence should record the exact fixture, compiler commit, Tableau Desktop version, whether the workbook opened without repair, and any screenshots or notes needed for future agents to trust the result.