Datasources¶

Warning: the compiler datasource surface is intentionally limited to packaged local CSV and Excel files. Do not design JSON for live databases, published Tableau datasources, SaaS connectors, Web Data Connectors, Hyper extracts, custom SQL, spatial files, or server authentication. Metadata-only datasources may appear in older low-level fixtures, but feature work and product docs should assume CSV or Excel.

Datasources define the fields agents can use in worksheets, filters, calculations, dashboards, actions, maps, and analytics. The JSON should describe semantic data intent; the compiler owns Tableau's connection XML, generated metadata records, and package paths.

Datasource Object¶

Use one object in datasources[] for each logical datasource.

{
  "name": "Orders",
  "caption": "Orders CSV",
  "connection": {
    "kind": "local_file",
    "format": "csv",
    "asset": "Data/orders.csv"
  },
  "columns": [
    {
      "name": "Category",
      "role": "dimension",
      "type": "nominal",
      "datatype": "string"
    },
    {
      "name": "Sales",
      "role": "measure",
      "type": "quantitative",
      "datatype": "real"
    }
  ]
}

Field	Type	Required	Values	Description
`name`	string	Yes	Stable datasource name	Used in qualified field refs such as `[Orders].[Sales]`. Must not be `Parameters`.
`caption`	string	No	Any display text	Tableau-facing label. Defaults to `name` when omitted.
`connection`	object	One of `connection` or `tables`	Local CSV/Excel connection	Single-table packaged file datasource.
`tables`	array	One of `connection` or `tables`	Table objects	Relationship-aware multi-table datasource.
`columns`	array	Yes	Column objects	Declares physical and calculated fields available to the compiler.
`relationships`	array	With `tables` only	Relationship objects	Equality links between declared table-backed columns.
`filters`	array	No	Datasource filter objects	Global filters applied to worksheets that use this datasource.
`semantic_values`	array	No	Semantic value objects	Geographic defaults used by generated maps.

Connection Object¶

Connections are always packaged local files. The asset value is the member path inside the .twbx, not necessarily the source path on disk.

{
  "kind": "local_file",
  "format": "csv",
  "asset": "Data/orders.csv",
  "header": true,
  "separator": ",",
  "table": "[orders#csv]"
}

Field	Type	Required	Values	Description
`kind`	string	Yes	`local_file`	The only supported connection kind.
`format`	string	Yes	`csv`, `excel`	CSV and Excel are the only supported file formats.
`asset`	string	Yes	Package member path	Must match a `package.assets[].member` entry.
`header`	boolean	No	`true`, `false`	Whether the file has a header row. Defaults to `true`.
`separator`	string	CSV only, optional	Usually `,`	CSV delimiter. Defaults to comma.
`table`	string	No	Tableau relation table name	Defaults from the file or sheet name.
`sheet`	string	Excel only, optional	Excel sheet name	Defaults to `Sheet1` for datasource-level Excel, or table `name` for table-level Excel.
`grid_origin`	string	Excel only, optional	Tableau Excel range descriptor	Defaults to a deterministic range based on declared columns.
`outcome`	integer	Excel only, optional	Positive integer	Tableau Excel relation outcome. Defaults to `6`.

Unsupported connection fields are intentionally rejected instead of passed through to Tableau.

Package Asset Object¶

Each file-backed datasource needs a packaged asset.

{
  "package": {
    "assets": [
      {
        "source": "assets/orders.csv",
        "member": "Data/orders.csv"
      }
    ]
  }
}

Field	Type	Required	Values	Description
`source`	string	Yes	Local path relative to the input config	File to place in the `.twbx`.
`member`	string	Yes	Stable package path	Path used by datasource `connection.asset`. Use POSIX-style `/` separators.

Column Object¶

Columns are the main field API. Every field used by worksheets, filters, calculations, maps, relationships, dashboards, or actions should be declared.

{
  "name": "Sales",
  "caption": "Sales",
  "role": "measure",
  "type": "quantitative",
  "datatype": "real",
  "default_format": "c\"$\"#,##0",
  "description": "Order revenue."
}

Field	Type	Required	Values	Description
`name`	string	Yes	Leaf or qualified field name	Stable logical name. Prefer leaf names inside `columns[]`; reference as `[Datasource].[Field]` elsewhere.
`role`	string	Yes	`dimension`, `measure`	Tableau field role. Dimensions are categorical/date-like; measures are numeric aggregations.
`type`	string	Yes	`nominal`, `ordinal`, `quantitative`	Semantic type used for validation and generated Tableau instances.
`datatype`	string	Yes	`boolean`, `date`, `datetime`, `integer`, `real`, `string`	Physical or calculated value type.
`caption`	string	No	Any display text	Tableau field caption. Does not change JSON references.
`default_format`	string	No	Tableau-compatible format string	Emitted as field default format. The compiler does not parse Tableau's full format language.
`description`	string	No	Plain text	Field description shown in Tableau metadata.
`hidden`	boolean	No	`true`, `false`	Hides the field in Tableau's data pane while preserving references.
`aliases`	array	No	Alias objects	Display aliases for physical boolean/string dimension members.
`geographic_role`	string	No	See geographic roles below	Tableau semantic role for generated maps.
`table`	string	Table-backed datasources only	Table `name`	Logical table this physical column belongs to.
`source`	string	No	Source field name	Physical field name in the backing table when it differs from `name`.
`calculation`	object	No	Calculation object	Tableau calculated field definition.

Role, Type, And Datatype¶

Field	Common pairings	Notes
`role: "dimension"`	`type: "nominal"` or `type: "ordinal"`	Use for category, region, segment, date buckets, IDs, booleans.
`role: "measure"`	`type: "quantitative"`	Use for sales, profit, quantity, rates, and other numeric measures.
`datatype: "date"` or `"datetime"`	Usually `role: "dimension"`, `type: "ordinal"`	Enables date shelves and date filters.
`datatype: "integer"` or `"real"`	Usually `role: "measure"`, `type: "quantitative"`	Enables aggregate shelves and quantitative filters.
`datatype: "string"`	Usually `role: "dimension"`, `type: "nominal"`	Enables categorical filters, aliases, and grouping-like views.

Alias Object¶

Aliases rename displayed members without changing raw data values.

{
  "aliases": [
    {
      "value": "Home Office",
      "alias": "Home office"
    },
    {
      "value": "Corporate",
      "alias": "Corporate customers"
    }
  ]
}

Field	Type	Required	Values	Description
`value`	string or boolean	Yes	Physical member value	Raw member value from the datasource.
`alias`	string	Yes	Display text	Tableau-facing member label.

Aliases are for physical boolean or string dimensions. They are not a substitute for calculated fields.

Calculation Object¶

Calculated fields are declared as columns. The compiler validates explicit references and emits the Tableau column instances required by shelves and marks.

{
  "name": "Profit Ratio",
  "role": "measure",
  "type": "quantitative",
  "datatype": "real",
  "calculation": {
    "formula": "SUM([Profit]) / SUM([Sales])",
    "references": ["Profit", "Sales"]
  }
}

Field	Type	Required	Values	Description
`formula`	string	Yes	Tableau formula text	Formula emitted into Tableau XML.
`references`	array	Yes	Field or parameter refs	Dependencies the compiler must resolve before output.
`lod`	object	No	LOD object	Enables supported level-of-detail calculations.
`table_calculation`	object	No	Table calculation metadata	Enables supported formula-backed table calculations.
`kind`	string	Some helper calculations	Helper kinds such as semantic z-score	Used only by compiler-owned calculation helpers.

Example FIXED LOD calculation:

{
  "name": "Order Profitable?",
  "role": "dimension",
  "type": "nominal",
  "datatype": "boolean",
  "calculation": {
    "formula": "{ FIXED [Order ID] : SUM([Profit]) } > 0",
    "references": ["Order ID", "Profit"],
    "lod": {
      "kind": "fixed"
    }
  }
}

Geographic Roles¶

Use geographic_role only on physical string dimensions.

Value	Use
`country_iso3166_2`	Country or region fields such as `US`.
`state_name`	State or province names.
`city_name`	City names.
`zip_code_name`	Postal code fields.

Example:

{
  "columns": [
    {
      "name": "Country/Region",
      "role": "dimension",
      "type": "nominal",
      "datatype": "string",
      "geographic_role": "country_iso3166_2"
    },
    {
      "name": "State/Province",
      "role": "dimension",
      "type": "nominal",
      "datatype": "string",
      "geographic_role": "state_name"
    }
  ]
}

Semantic Value Object¶

Semantic values provide datasource-level geographic defaults.

{
  "semantic_values": [
    {
      "key": "country_name",
      "value": "United States"
    },
    {
      "key": "state_name",
      "value": null
    }
  ]
}

Field	Type	Required	Values	Description
`key`	string	Yes	`country_name`, `state_name`	Semantic default key.
`value`	string or null	Yes	Quoted value or `null`	Default value emitted into Tableau semantic metadata.

Table Object¶

Use tables[] for a relationship-aware datasource. Each table has its own local file connection.

{
  "name": "Orders",
  "connection": {
    "kind": "local_file",
    "format": "excel",
    "asset": "Data/sales_model.xlsx",
    "sheet": "Orders",
    "grid_origin": "A1:D500:no:A1:D500:0",
    "outcome": 6
  }
}

Field	Type	Required	Values	Description
`name`	string	Yes	Stable table name	Used by `columns[].table`.
`caption`	string	No	Any display text	Tableau-facing table caption.
`connection`	object	Yes	Local CSV/Excel connection	Connection for this logical table.

Relationship Object¶

Relationships connect columns from different tables in the same datasource.

{
  "relationships": [
    {
      "left": "[Sales Model].[Region]",
      "right": "[Sales Model].[Region Manager Key]"
    }
  ]
}

Field	Type	Required	Values	Description
`left`	string	Yes	Qualified column ref	A declared physical column in one table.
`right`	string	Yes	Qualified column ref	A declared physical column in another table with compatible datatype.

Datasource Filter Object¶

Datasource filters apply to every worksheet using the datasource. Prefer worksheet filters for view-specific constraints.

Categorical Filter¶

{
  "field": "[Orders].[Region]",
  "kind": "categorical",
  "members": ["Central", "East", "West"]
}

Quantitative Filter¶

{
  "field": "[Orders].[Sales]",
  "kind": "quantitative",
  "min": 0,
  "max": 100000
}

Field	Type	Required	Values	Description
`field`	string	Yes	Qualified field ref	Field in the same datasource.
`kind`	string	Yes	`categorical`, `quantitative`	Filter shape.
`members`	array	Categorical only	Member values	Included members.
`min`	number	Quantitative only, optional	Number	Lower bound.
`max`	number	Quantitative only, optional	Number	Upper bound.

Datasource filters currently support categorical include filters over physical nominal/ordinal dimensions and quantitative range filters over physical integer/real measures.

Parameter Object¶

Parameters are top-level workbook objects, but they behave like datasource inputs because calculations, controls, and reference lines consume them.

{
  "name": "Sales Target",
  "caption": "Sales target",
  "type": "quantitative",
  "datatype": "real",
  "value": 500,
  "domain": {
    "kind": "range",
    "min": 0,
    "max": 1500,
    "step": 50
  }
}

Field	Type	Required	Values	Description
`name`	string	Yes	Stable parameter name	Used by controls, calculations, title tokens, and reference lines.
`caption`	string	No	Any display text	Tableau-facing label. Defaults to `name`.
`type`	string	Yes	`nominal`, `ordinal`, `quantitative`	Semantic type.
`datatype`	string	Yes	`boolean`, `date`, `datetime`, `integer`, `real`, `string`	Parameter value datatype.
`value`	boolean, number, or string	Yes	Must match `datatype`	Initial open-time value.
`domain`	object	Yes	List or range domain	Allowed values.

List Domain¶

{
  "domain": {
    "kind": "list",
    "members": ["Sales", "Profit", "Quantity"]
  }
}

Field	Type	Required	Values	Description
`kind`	string	Yes	`list`	Explicit member domain.
`members`	array	Yes	Values matching parameter datatype	Allowed values. The current `value` must be included.

Range Domain¶

{
  "domain": {
    "kind": "range",
    "min": 0,
    "max": 1500,
    "step": 50
  }
}

Field	Type	Required	Values	Description
`kind`	string	Yes	`range`	Numeric range domain.
`min`	number	No	Number	Lower bound.
`max`	number	No	Number	Upper bound.
`step`	number	No	Positive number	Step size for controls.

Range domains are for integer and real parameters.

Local CSV Example¶

{
  "version": "1.0",
  "package": {
    "assets": [
      {
        "source": "assets/orders.csv",
        "member": "Data/orders.csv"
      }
    ]
  },
  "datasources": [
    {
      "name": "Orders",
      "caption": "Orders CSV",
      "connection": {
        "kind": "local_file",
        "format": "csv",
        "asset": "Data/orders.csv"
      },
      "columns": [
        {
          "name": "Order Date",
          "role": "dimension",
          "type": "ordinal",
          "datatype": "date"
        },
        {
          "name": "Category",
          "role": "dimension",
          "type": "nominal",
          "datatype": "string"
        },
        {
          "name": "Sales",
          "role": "measure",
          "type": "quantitative",
          "datatype": "real",
          "default_format": "c\"$\"#,##0"
        }
      ]
    }
  ]
}

Local Excel Relationship Example¶

{
  "version": "1.0",
  "package": {
    "assets": [
      {
        "source": "assets/sales_model.xlsx",
        "member": "Data/sales_model.xlsx"
      }
    ]
  },
  "datasources": [
    {
      "name": "Sales Model",
      "caption": "Sales Model",
      "tables": [
        {
          "name": "Orders",
          "connection": {
            "kind": "local_file",
            "format": "excel",
            "asset": "Data/sales_model.xlsx",
            "sheet": "Orders"
          }
        },
        {
          "name": "People",
          "connection": {
            "kind": "local_file",
            "format": "excel",
            "asset": "Data/sales_model.xlsx",
            "sheet": "People"
          }
        }
      ],
      "columns": [
        {
          "name": "Region",
          "role": "dimension",
          "type": "nominal",
          "datatype": "string",
          "table": "Orders"
        },
        {
          "name": "Sales",
          "role": "measure",
          "type": "quantitative",
          "datatype": "real",
          "table": "Orders"
        },
        {
          "name": "Region Manager Key",
          "role": "dimension",
          "type": "nominal",
          "datatype": "string",
          "table": "People",
          "source": "Region"
        },
        {
          "name": "Regional Manager",
          "role": "dimension",
          "type": "nominal",
          "datatype": "string",
          "table": "People",
          "source": "Manager"
        }
      ],
      "relationships": [
        {
          "left": "[Sales Model].[Region]",
          "right": "[Sales Model].[Region Manager Key]"
        }
      ]
    }
  ]
}

Field Reference Rules¶

Reference	Use
`[Orders].[Sales]`	Most explicit and safest form.
`Sales`	Accepted in some declaration-local contexts, but less clear for agents.
`[Parameters].[Sales Target]`	Parameter reference inside calculations.
Generated `usr:` or `none:` names	Do not write these in config. The compiler creates them.

Unsupported Datasource Surfaces¶

Surface	Status
Published Tableau datasources	Unsupported and not planned for this compiler surface.
Live database connectors	Unsupported. Use packaged CSV/Excel extracts as inputs instead.
Cloud/SaaS connectors	Unsupported.
Web Data Connectors	Unsupported.
Hyper extract generation	Unsupported.
Custom SQL	Unsupported.
Spatial file connections	Unsupported.
Authentication, server, or credential fields	Unsupported and should be rejected.