Dataface YAML Schema Reference

Face

AuthoredFace (dataface) definition from YAML.

Field	Type	Optional	Description
title	str	✓	Dashboard title displayed at the top.
description	str	✓	Description text for the dashboard.
tags	list[str]	✓	Tags for categorization and search.
aliases	list[str]	✓	Additional URLs that redirect to this face's canonical file-path URL. Each entry must be absolute (leading /). Requests to these URLs are redirected (302) to the face's real path, query string preserved. Valid on .yml, .yaml, .md, and folder index.* faces.
docs	str	✓	Relative path under the docs site for the canonical doc page that explains this face. Surfaced as a 'Docs →' link in the playground gallery when DFT_DOCS_URL is set.
text	str	✓	Markdown text content for text-only sections.
allow_html	bool	✓	Render the face's body text as raw HTML via foreignObject instead of markdown. TRUSTED-CONTENT ONLY: the HTML (including any Jinja-interpolated values) is rendered as-authored — this is NOT a security sandbox. mdsvg strips <script>/event-handlers as a best-effort guard, not a guarantee. Enable only on first-party faces you fully control.
source	str	✓	Default source name for all queries in this face. Inheritable via meta.yaml cascade.
variables	dict[str, Variable | VariableRef]	✓	Variable definitions for dynamic filtering and UI controls.
queries	dict[str, SqlQuery | MetricflowQuery | DbtModelQuery | HttpQuery | ValuesQuery | SchemaQuery | LookmlQuery | QueryRef]	✓	Named query definitions (SQL, CSV, MetricFlow, HTTP, etc.).
charts	dict[str, BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | LayeredChart | CalloutChart | SparkBarChart | ChartRef]	✓	Named chart definitions. When no explicit layout is present, charts render as an implicit row layout in authored order.
rows	list[str | Face | BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | LayeredChart | CalloutChart | SparkBarChart | ForeachItem | dict[str, BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | LayeredChart | CalloutChart | SparkBarChart]]	✓	Vertical stack layout: list of chart names or inline chart/face definitions.
cols	list[str | Face | BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | LayeredChart | CalloutChart | SparkBarChart | ForeachItem | dict[str, BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | LayeredChart | CalloutChart | SparkBarChart]]	✓	Horizontal layout: list of chart names or inline chart/face definitions.
grid	GridLayout	✓	CSS-grid style layout with explicit row/column placement.
tabs	TabLayout	✓	Tabbed navigation layout where each tab contains its own layout.
card_gap	bool	✓	When True, adds gap between cards. Default: cards are edge-to-edge (0 gap).
chart_focus	str	✓	Render only this named chart with its dependent variables (useful for embedding or SVG export).
details	FaceDetails	✓	Collapsible section metadata. String shorthand: details: 'text' → FaceDetails(summary='text'). Block form: details: {summary: ..., expanded_title: ..., expanded: false}.
id	str	✓	Explicit ID for this face. Auto-generated from filename if omitted.
style	Style	✓	Style patch (background, padding, border, etc.). Background and semantic color tokens (accent, muted) cascade to nested child faces.
width	str | int	✓	Width when nested (e.g., '50%', '400px', or an integer in pixels).
height	str | int	✓	Height when nested (e.g., '300px' or an integer in pixels).
visible	bool | str | SingleRowBoolProbe	✓	Controls whether this layout item is rendered. Accepts a bool, variable name, Jinja expression, or {query, column} probe.
extends	str | list[str]	✓	Face name(s) or relative path(s) this face inherits from, low to high priority.
auto_link	bool	✓	When True, table charts with no explicit link: automatically link each row to its canonical /data/<source>/<schema>/<table>/detail/ page. Default off. Explicit link: always wins; set link: ~ to suppress per chart.

Variable

Variable definition from YAML.

Field	Type	Optional	Description
input	enum: "auto", "select", "multiselect", "input", "text", "number", "textarea", "slider", "range", "date", "datepicker", "daterange", "checkbox", "radio"	✓	UI control type (select, multiselect, slider, daterange, etc.). 'auto' detects from options.
label	str	✓	Display label shown above the input control.
description	str	✓	Help text shown below the input control.
default	Any	✓	Default value used when no URL param is set.
placeholder	str	✓	Placeholder text shown in the input when empty.
required	bool	✓	When True, a value must be provided before queries execute.
visible	bool	✓	When False, the variable is not rendered in the UI but can still be set via URL params.
enabled	bool | str | SingleRowBoolProbe	✓	Enable this control. Accepts: static bool; a variable name or Jinja boolean expression string (no {{ }} required — bare names auto-wrap); or a {query, column} form that reads a single boolean cell from a named query. None = enabled. Absent variable in a string expression raises (use a default).
column	str	✓	Column name in the query result to use as option values.
query	str | SqlQuery | MetricflowQuery | DbtModelQuery | HttpQuery | ValuesQuery | SchemaQuery | LookmlQuery	✓	Query name or inline query definition for populating options.
dimension	str	✓	MetricFlow dimension name for populating options.
measure	str	✓	MetricFlow measure name for populating options.
model	str	✓	dbt model name for populating options.
options	VariableOptions	✓	Static or query-driven option list configuration.
data_type	str	✓	Upstream data-type hint preserved through migrations (e.g. 'string', 'number'). Informational; not currently consumed at compile time.
min	int | float	✓	Minimum value for slider/range inputs.
max	int | float	✓	Maximum value for slider/range inputs.
step	int | float	✓	Step size for slider/range inputs.
operator	str	✓	SQL operator used when generating filter expressions (e.g., '=', 'IN', 'LIKE').

SqlQuery

Raw SQL query — the default query type.

Field	Type	Optional	Description
source	str | dict[str, Any]	✓	Source name reference, or an inline file path (e.g. ./data/sales.csv). File paths are detected by / or data file extension. An inline connection-bearing dict ({type: postgres, ...}) is rejected at compile time — reference a named source instead.
description	str	✓	Human-readable description of the query. Used by AI search and tooling.
filters	dict[str, Any]	✓	Declarative column filters injected into the query's WHERE clause (SQL/DuckDB sources).
limit	int	✓	Maximum number of rows returned.
ignore	list[str]	✓	Diagnostic codes to suppress for this query (e.g., ['fanout_risk', 'reaggregation']).
cache	bool	✓	Set to false to opt this query out of result caching. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references.
type	enum: "sql"	✓	Query adapter type.
sql	str	✓	SQL query string. Supports Jinja2 templates referencing variables.
setup_sql	str	✓	Non-nestable SQL preamble executed before the main query (e.g., CREATE TEMP FUNCTION).
target	str	✓	dbt target name for queries against a dbt_profile source (defaults to 'dev').

MetricflowQuery

dbt Semantic Layer (MetricFlow) query.

Field	Type	Optional	Description
source	str | dict[str, Any]	✓	Source name reference, or an inline file path (e.g. ./data/sales.csv). File paths are detected by / or data file extension. An inline connection-bearing dict ({type: postgres, ...}) is rejected at compile time — reference a named source instead.
description	str	✓	Human-readable description of the query. Used by AI search and tooling.
filters	dict[str, Any]	✓	Declarative column filters injected into the query's WHERE clause (SQL/DuckDB sources).
limit	int	✓	Maximum number of rows returned.
ignore	list[str]	✓	Diagnostic codes to suppress for this query (e.g., ['fanout_risk', 'reaggregation']).
cache	bool	✓	Set to false to opt this query out of result caching. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references.
type	enum: "metricflow"	✓	Query adapter type.
metrics	list[str]	✓	MetricFlow metric names to query.
dimensions	list[str]	✓	MetricFlow dimensions to include in the result.
time_grain	enum: "day", "week", "month", "quarter", "year"	✓	MetricFlow time grain for time-series dimensions (day, week, month, quarter, year).

DbtModelQuery

Query against a dbt model directly.

Field	Type	Optional	Description
source	str | dict[str, Any]	✓	Source name reference, or an inline file path (e.g. ./data/sales.csv). File paths are detected by / or data file extension. An inline connection-bearing dict ({type: postgres, ...}) is rejected at compile time — reference a named source instead.
description	str	✓	Human-readable description of the query. Used by AI search and tooling.
filters	dict[str, Any]	✓	Declarative column filters injected into the query's WHERE clause (SQL/DuckDB sources).
limit	int	✓	Maximum number of rows returned.
ignore	list[str]	✓	Diagnostic codes to suppress for this query (e.g., ['fanout_risk', 'reaggregation']).
cache	bool	✓	Set to false to opt this query out of result caching. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references.
type	enum: "dbt_model"	✓	Query adapter type.
model	str	✓	dbt model name to query directly.
columns	list[str]	✓	Column subset to select from the dbt model.
target	str	✓	dbt target name (defaults to 'dev').

HttpQuery

REST API query.

Field	Type	Optional	Description
source	str | dict[str, Any]	✓	Source name reference, or an inline file path (e.g. ./data/sales.csv). File paths are detected by / or data file extension. An inline connection-bearing dict ({type: postgres, ...}) is rejected at compile time — reference a named source instead.
description	str	✓	Human-readable description of the query. Used by AI search and tooling.
filters	dict[str, Any]	✓	Declarative column filters injected into the query's WHERE clause (SQL/DuckDB sources).
limit	int	✓	Maximum number of rows returned.
ignore	list[str]	✓	Diagnostic codes to suppress for this query (e.g., ['fanout_risk', 'reaggregation']).
cache	bool	✓	Set to false to opt this query out of result caching. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references.
type	enum: "http"	✓	Query adapter type.
url	str	✓	HTTP endpoint URL for REST API queries.
method	enum: "GET", "POST", "PUT", "DELETE", "PATCH"	✓	HTTP method (GET, POST, PUT, DELETE, PATCH).
headers	dict[str, str]	✓	HTTP request headers.
params	dict[str, Any]	✓	HTTP query string parameters.
body	dict[str, Any] | str	✓	HTTP request body for POST/PUT queries.
json_path	str	✓	JSONPath expression to extract tabular data from the HTTP response.

ValuesQuery

Inline rows embedded in YAML.

Field	Type	Optional	Description
source	str | dict[str, Any]	✓	Source name reference, or an inline file path (e.g. ./data/sales.csv). File paths are detected by / or data file extension. An inline connection-bearing dict ({type: postgres, ...}) is rejected at compile time — reference a named source instead.
description	str	✓	Human-readable description of the query. Used by AI search and tooling.
filters	dict[str, Any]	✓	Declarative column filters injected into the query's WHERE clause (SQL/DuckDB sources).
limit	int	✓	Maximum number of rows returned.
ignore	list[str]	✓	Diagnostic codes to suppress for this query (e.g., ['fanout_risk', 'reaggregation']).
cache	bool	✓	Set to false to opt this query out of result caching. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references.
type	enum: "values"	✓	Query adapter type.
rows	list[dict[str, Any]]	✓	Inline data rows (list of row dicts).
values	list[list[Any]]	✓	Inline row-oriented data (list of lists) for the compact 'columns + values' syntax.
columns	list[str]	✓	Column names for the compact 'columns + values' syntax.

SchemaQuery

dbt source schema query.

Field	Type	Optional	Description
source	str | dict[str, Any]	✓	Source name reference, or an inline file path (e.g. ./data/sales.csv). File paths are detected by / or data file extension. An inline connection-bearing dict ({type: postgres, ...}) is rejected at compile time — reference a named source instead.
description	str	✓	Human-readable description of the query. Used by AI search and tooling.
filters	dict[str, Any]	✓	Declarative column filters injected into the query's WHERE clause (SQL/DuckDB sources).
limit	int	✓	Maximum number of rows returned.
ignore	list[str]	✓	Diagnostic codes to suppress for this query (e.g., ['fanout_risk', 'reaggregation']).
cache	bool	✓	Set to false to opt this query out of result caching. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references.
type	enum: "schema"	✓	Query adapter type.
schema	str	✓	Schema name for schema queries (YAML key: schema).
table	str	✓	Table name for schema queries.
column	str	✓	Column name for schema queries.

LookmlQuery

LookML semantic query — compiled to SQL through likeml at compile time.

Field	Type	Optional	Description
source	str | dict[str, Any]	✓	Source name reference, or an inline file path (e.g. ./data/sales.csv). File paths are detected by / or data file extension. An inline connection-bearing dict ({type: postgres, ...}) is rejected at compile time — reference a named source instead.
description	str	✓	Human-readable description of the query. Used by AI search and tooling.
filters	dict[str, Any]	✓	RAW Looker filter expressions keyed by 'view.field' (e.g. "13 months", "gold") — translated to SQL predicates by likeml.
limit	int	✓	Maximum number of rows returned.
ignore	list[str]	✓	Diagnostic codes to suppress for this query (e.g., ['fanout_risk', 'reaggregation']).
cache	bool	✓	Set to false to opt this query out of result caching. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references.
type	enum: "lookml"	✓	Query adapter type.
explore	str	✓	LookML explore name. Presence of this key infers type: lookml.
merge	list[dict[str, Any]]	✓	LookML merge sources — a list of source specs. Each is either an explore spec ({explore, fields, filters?, merge_on?}) or a query reference ({query, columns, merge_on?}) for a derived source such as a table-calc wrapper. First is the primary; each secondary's merge_on maps its key to the primary's. Presence of this key infers type: lookml. Compiled to a FULL OUTER JOIN via likeml.
fields	list[str]	✓	Qualified 'view.field' refs to select. Optional at authoring time: collected from chart channels when absent.
sorts	list[str]	✓	Looker sort clauses, e.g. ['view.field', 'view.other desc']. Lowered to ORDER BY via likeml.
pivots	list[str]	✓	Qualified 'view.field' refs to pivot on.
pivots_unwrapped	bool	✓	Which of Looker's two pivot SQL shapes to emit: False/None = wrapped (5-layer DENSE_RANK), True = plain GROUP BY.
total	bool	✓	Looker grand-totals flag.
subtotals	list[str]	✓	Dimension refs to subtotal via GROUP BY ROLLUP.
filter_expression	str	✓	Looker query-level free-form boolean filter over ${view.field} refs.
dynamic_fields	list[dict[str, Any]]	✓	Looker dynamic fields: custom measures / custom dimensions synthesized into SQL. Table calculations compose as a derived wrapper query, not here.
column_limit	int	✓	Looker column_limit — caps wrapped-pivot columns.

BarChart

Authored patch for bar and histogram charts.

Field	Type	Optional	Description
type	enum: "bar", "histogram"		Bar or histogram chart type.
conditional_formatting	dict[str, FieldConditionalFormatting]	✓	Discrete rule-driven style overrides indexed by column name.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | DbtModelQuery | HttpQuery | ValuesQuery | SchemaQuery | LookmlQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point: 'model.explore' (LookML model name and explore joined by a dot). Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
title	str	✓	Chart title displayed above the chart (not used on type: kpi).
subtitle	str	✓	Chart subtitle displayed below the title.
x	str	✓	X-axis column name from the query result.
y	str | list[str]	✓	Y-axis column name(s). Accepts a single column or list for multi-series charts.
x_label	str	✓	Custom label for the X axis.
y_label	str	✓	Custom label for the Y axis.
color	str	✓	Color data channel: bare column name only.
sort	ChartSort	✓	Sort configuration: column to sort by and direction (asc/desc).
multiples	MultiplesConfig	✓	Partition this chart into small multiples by a rows column (vertical stack), a columns column (side by side), or both (grid). Panels share one measure scale by default.
data_table	ChartDataTable	✓	Optional mini data-grid attached below/above the chart.
height	int | float	✓	Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts.
width	int | float	✓	Chart width hint in pixels. Positive number only. Used by the label-overlap heuristic to determine whether x-axis labels need tilting. Does not override the layout slot width — the chart still fills its allocated container. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts.
style	BarChartStyle	✓	Chart-local style overrides.

LineChart

Authored patch for line charts.

Field	Type	Optional	Description
type	enum: "line"		Line chart type.
conditional_formatting	dict[str, FieldConditionalFormatting]	✓	Discrete rule-driven style overrides indexed by column name.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | DbtModelQuery | HttpQuery | ValuesQuery | SchemaQuery | LookmlQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point: 'model.explore' (LookML model name and explore joined by a dot). Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
title	str	✓	Chart title displayed above the chart (not used on type: kpi).
subtitle	str	✓	Chart subtitle displayed below the title.
x	str	✓	X-axis column name from the query result.
y	str | list[str]	✓	Y-axis column name(s). Accepts a single column or list for multi-series charts.
x_label	str	✓	Custom label for the X axis.
y_label	str	✓	Custom label for the Y axis.
color	str	✓	Color data channel: bare column name only.
sort	ChartSort	✓	Sort configuration: column to sort by and direction (asc/desc).
multiples	MultiplesConfig	✓	Partition this chart into small multiples by a rows column (vertical stack), a columns column (side by side), or both (grid). Panels share one measure scale by default.
data_table	ChartDataTable	✓	Optional mini data-grid attached below/above the chart.
height	int | float	✓	Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts.
width	int | float	✓	Chart width hint in pixels. Positive number only. Used by the label-overlap heuristic to determine whether x-axis labels need tilting. Does not override the layout slot width — the chart still fills its allocated container. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts.
style	LineChartStyle	✓	Chart-local style overrides.

AreaChart

Authored patch for area charts.

Field	Type	Optional	Description
type	enum: "area"		Area chart type.
conditional_formatting	dict[str, FieldConditionalFormatting]	✓	Discrete rule-driven style overrides indexed by column name.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | DbtModelQuery | HttpQuery | ValuesQuery | SchemaQuery | LookmlQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point: 'model.explore' (LookML model name and explore joined by a dot). Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
title	str	✓	Chart title displayed above the chart (not used on type: kpi).
subtitle	str	✓	Chart subtitle displayed below the title.
x	str	✓	X-axis column name from the query result.
y	str | list[str]	✓	Y-axis column name(s). Accepts a single column or list for multi-series charts.
x_label	str	✓	Custom label for the X axis.
y_label	str	✓	Custom label for the Y axis.
color	str	✓	Color data channel: bare column name only.
sort	ChartSort	✓	Sort configuration: column to sort by and direction (asc/desc).
multiples	MultiplesConfig	✓	Partition this chart into small multiples by a rows column (vertical stack), a columns column (side by side), or both (grid). Panels share one measure scale by default.
data_table	ChartDataTable	✓	Optional mini data-grid attached below/above the chart.
height	int | float	✓	Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts.
width	int | float	✓	Chart width hint in pixels. Positive number only. Used by the label-overlap heuristic to determine whether x-axis labels need tilting. Does not override the layout slot width — the chart still fills its allocated container. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts.
style	AreaChartStyle	✓	Chart-local style overrides.

ScatterChart

Authored patch for scatter charts.

Field	Type	Optional	Description
type	enum: "scatter"		Scatter chart type.
conditional_formatting	dict[str, FieldConditionalFormatting]	✓	Discrete rule-driven style overrides indexed by column name.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | DbtModelQuery | HttpQuery | ValuesQuery | SchemaQuery | LookmlQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point: 'model.explore' (LookML model name and explore joined by a dot). Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
title	str	✓	Chart title displayed above the chart (not used on type: kpi).
subtitle	str	✓	Chart subtitle displayed below the title.
x	str	✓	X-axis column name from the query result.
y	str | list[str]	✓	Y-axis column name(s). Accepts a single column or list for multi-series charts.
x_label	str	✓	Custom label for the X axis.
y_label	str	✓	Custom label for the Y axis.
color	str	✓	Color data channel: bare column name only.
sort	ChartSort	✓	Sort configuration: column to sort by and direction (asc/desc).
multiples	MultiplesConfig	✓	Partition this chart into small multiples by a rows column (vertical stack), a columns column (side by side), or both (grid). Panels share one measure scale by default.
data_table	ChartDataTable	✓	Optional mini data-grid attached below/above the chart.
height	int | float	✓	Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts.
width	int | float	✓	Chart width hint in pixels. Positive number only. Used by the label-overlap heuristic to determine whether x-axis labels need tilting. Does not override the layout slot width — the chart still fills its allocated container. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts.
size	str	✓	Column used to size-encode data points (quantitative).
shape	str	✓	Column used to shape-encode data points (categorical).
style	ScatterChartStyle	✓	Chart-local style overrides.

HeatmapChart

Authored patch for heatmap charts.

Field	Type	Optional	Description
type	enum: "heatmap"		Heatmap chart type.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | DbtModelQuery | HttpQuery | ValuesQuery | SchemaQuery | LookmlQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point: 'model.explore' (LookML model name and explore joined by a dot). Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
title	str	✓	Chart title displayed above the chart (not used on type: kpi).
subtitle	str	✓	Chart subtitle displayed below the title.
x	str	✓	X-axis column name from the query result.
y	str | list[str]	✓	Y-axis column name(s). Accepts a single column or list for multi-series charts.
x_label	str	✓	Custom label for the X axis.
y_label	str	✓	Custom label for the Y axis.
color	str	✓	Color data channel: bare column name only.
sort	ChartSort	✓	Sort configuration: column to sort by and direction (asc/desc).
multiples	MultiplesConfig	✓	Partition this chart into small multiples by a rows column (vertical stack), a columns column (side by side), or both (grid). Panels share one measure scale by default.
data_table	ChartDataTable	✓	Optional mini data-grid attached below/above the chart.
height	int | float	✓	Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts.
width	int | float	✓	Chart width hint in pixels. Positive number only. Used by the label-overlap heuristic to determine whether x-axis labels need tilting. Does not override the layout slot width — the chart still fills its allocated container. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts.
style	HeatmapChartStyle	✓	Chart-local style overrides.

PieChart

Authored patch for pie and donut charts.

Field	Type	Optional	Description
type	enum: "pie", "donut"		Pie or donut chart type.
theta	str		Column for angular encoding in pie (arc) charts.
conditional_formatting	dict[str, FieldConditionalFormatting]	✓	Discrete rule-driven style overrides indexed by column name.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | DbtModelQuery | HttpQuery | ValuesQuery | SchemaQuery | LookmlQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point: 'model.explore' (LookML model name and explore joined by a dot). Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
title	str	✓	Chart title displayed above the chart (not used on type: kpi).
subtitle	str	✓	Chart subtitle displayed below the title.
color	str	✓	Color data channel: bare column name only.
total	ChartTotal	✓	Donut center total.
style	PieChartStyle	✓	Chart-local style overrides.

KpiChart

Authored patch for KPI (key performance indicator) charts.

Field	Type	Optional	Description
type	enum: "kpi"		KPI chart type.
value	str		Column reference (string column name) for the headline number/text.
conditional_formatting	dict[str, FieldConditionalFormatting]	✓	Discrete rule-driven style overrides indexed by column name.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | DbtModelQuery | HttpQuery | ValuesQuery | SchemaQuery | LookmlQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point: 'model.explore' (LookML model name and explore joined by a dot). Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
label	str	✓	KPI label rendered above the headline value.
variant	enum: "stacked", "inline", "compact"	✓	Layout variant. 'stacked' (default) shows value, label, and support on three vertical lines. 'inline' lays value, label, and support out on a single baseline-aligned row. 'compact' is 2-column — big value on the left, up to two stacked lines on the right with the bottom line sharing baseline with the value; a lone support block splits across the two right-column lines.
support	KpiSupportConfig	✓	Optional support line beneath the KPI value.
style	KpiChartStyle	✓	Chart-local style overrides.
background	str | dict[str, Any]	✓	Gradient background channel — {column, scale} shape. Paints the card background by the value's position in the scale. See channel.py parse_style_channel for the full grammar.

TableChart

Authored patch for table charts.

Field	Type	Optional	Description
type	enum: "table"		Table chart type.
conditional_formatting	dict[str, FieldConditionalFormatting]	✓	Discrete rule-driven style overrides indexed by column name.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | DbtModelQuery | HttpQuery | ValuesQuery | SchemaQuery | LookmlQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point: 'model.explore' (LookML model name and explore joined by a dot). Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
title	str	✓	Chart title displayed above the chart (not used on type: kpi).
subtitle	str	✓	Chart subtitle displayed below the title.
style	TableChartStyle	✓	Chart-local style overrides.
rows	list[str]	✓	Fields whose distinct values form the row dimension of a pivot cross-tab. Each string is a column name from the query result. Omit for flat (non-pivot) tables.
columns	list[str]	✓	Fields whose distinct values become column headers in a pivot cross-tab. Multiple fields create a nested multi-dimension pivot (outer → inner). Omit for flat tables.
values	list[str]	✓	Measure fields that fill pivot cells. Each string is a column name from the query result. When omitted, all query columns not claimed by rows or columns are used.

PointMapChart

Authored patch for point_map and bubble_map charts.

Field	Type	Optional	Description
type	enum: "point_map", "bubble_map"		Point map or bubble map chart type.
conditional_formatting	dict[str, FieldConditionalFormatting]	✓	Discrete rule-driven style overrides indexed by column name.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | DbtModelQuery | HttpQuery | ValuesQuery | SchemaQuery | LookmlQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point: 'model.explore' (LookML model name and explore joined by a dot). Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
title	str	✓	Chart title displayed above the chart (not used on type: kpi).
subtitle	str	✓	Chart subtitle displayed below the title.
projection	str | Projection	✓	Map projection name or Vega-Lite projection config.
color	str	✓	Color data channel: bare column name only.
geo	str | dict[str, Any]	✓	Named GeoJSON boundary source, or inline GeoJSON spec, for geoshape charts.
geo_source	str	✓	Named geographic data source for loading GeoJSON boundaries.
lookup	str	✓	Data column to join against geographic data (map join key).
value	str	✓	Data column mapped to the fill color.
latitude	str	✓	Column containing latitude values for point/bubble maps.
longitude	str	✓	Column containing longitude values for point/bubble maps.
size	str	✓	Data column used to scale bubble radius (quantitative). Only meaningful on bubble_map.
basemap	BasemapConfig	✓	Tile-layer configuration for the map background.
style	PointMapChartStyle	✓	Chart-local style overrides.

GeoshapeChart

Authored patch for map and geoshape charts.

Field	Type	Optional	Description
type	enum: "map", "geoshape"		Map or geoshape chart type.
conditional_formatting	dict[str, FieldConditionalFormatting]	✓	Discrete rule-driven style overrides indexed by column name.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | DbtModelQuery | HttpQuery | ValuesQuery | SchemaQuery | LookmlQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point: 'model.explore' (LookML model name and explore joined by a dot). Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
title	str	✓	Chart title displayed above the chart (not used on type: kpi).
subtitle	str	✓	Chart subtitle displayed below the title.
projection	str | Projection	✓	Map projection name or Vega-Lite projection config.
color	str	✓	Color data channel: bare column name only.
geo	str | dict[str, Any]	✓	Named GeoJSON boundary source, or inline GeoJSON spec, for geoshape charts.
geo_source	str	✓	Named geographic data source for loading GeoJSON boundaries.
lookup	str	✓	Data column to join against geographic data (map join key).
value	str	✓	Data column mapped to the fill color.
latitude	str	✓	Column containing latitude values for point/bubble maps.
longitude	str	✓	Column containing longitude values for point/bubble maps.
style	GeoshapeChartStyle	✓	Chart-local style overrides.

LayeredChart

Authored patch for layered multi-mark charts.

Field	Type	Optional	Description
type	enum: "layered"		Layered chart type.
layers	list[Layer]		Layers for multi-mark charts. Each layer is a chart definition.
conditional_formatting	dict[str, FieldConditionalFormatting]	✓	Discrete rule-driven style overrides indexed by column name.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | DbtModelQuery | HttpQuery | ValuesQuery | SchemaQuery | LookmlQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point: 'model.explore' (LookML model name and explore joined by a dot). Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
title	str	✓	Chart title displayed above the chart (not used on type: kpi).
subtitle	str	✓	Chart subtitle displayed below the title.
x	str	✓	Shared X-axis column name for all layers.
sort	ChartSort	✓	Sort configuration for the shared X axis.
x_domain	enum: "union", "primary"	✓	Controls how x-values from multiple layer queries are combined.
data_table	ChartDataTable	✓	Optional mini data-grid attached to the chart.
format	str | FormatConfig	✓	Number format override.
style	LayeredChartStyle	✓	Chart-local style overrides.

CalloutChart

Static callout/message chart. Minimal — no chrome, no styling, no query.

Field	Type	Optional	Description
type	enum: "callout"		Callout chart type.
message	str		Static message content.
title	str	✓	Optional chart title shown above the message.
style	CalloutChartStyle	✓	Chart-local style overrides (tone).
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.

SparkBarChart

Authored patch for spark_bar charts (compact horizontal bars).

Field	Type	Optional	Description
type	enum: "spark_bar"		SparkBar chart type.
id	str	✓	Explicit chart ID (auto-generated from the chart's YAML key if omitted).
description	str	✓	Human-readable description used by AI search and context tooltips.
query	str | SqlQuery | MetricflowQuery | DbtModelQuery | HttpQuery | ValuesQuery | SchemaQuery | LookmlQuery | QueryRef	✓	Named query reference, inline AuthoredQuery, or SQL string shorthand.
link	str	✓	Click-through URL template for drill-down links.
model	str	✓	Semantic-layer entry point: 'model.explore' (LookML model name and explore joined by a dot). Mutually exclusive with query:.
warnings_ignore	list[str]	✓	Codes of render warnings to suppress for this chart.
title	str	✓	Chart title displayed above the chart (not used on type: kpi).
subtitle	str	✓	Chart subtitle displayed below the title.
x	str	✓	X-axis (label) column name.
y	str | list[str]	✓	Y-axis (value) column name(s).
style	SparkBarChartStyle	✓	Chart-local style overrides.

ForeachItem

Top-level foreach construct in a layout list.

Field	Type	Description
foreach	ForeachConfig	foreach loop configuration with query, as, and items.

GridLayout

Grid layout configuration.

Field	Type	Optional	Description
items	list[GridItem]		List of grid items with position and span configuration.
columns	int	✓	Number of grid columns (default: 24).
row_height	str	✓	Default row height as a CSS value (e.g., '200px').
gap	enum: "sm", "md", "lg", "xl"	✓	Gap between grid cells (sm, md, lg, xl).
default_width	int	✓	Default column span for items that don't specify width.
default_height	int	✓	Default row span for items that don't specify height.

TabLayout

Tab layout configuration.

Field	Type	Optional	Description
items	list[TabItem]		List of tab items.
id	str	✓	Variable name and URL param base for tab selection (auto-generated if omitted).
position	enum: "top", "left"	✓	Tab bar position (top or left).
default	str	✓	Default tab title to activate on load.

FaceDetails

Collapsible section metadata for a face.

Field	Type	Optional	Description
summary	str		Label shown when the section is collapsed.
expanded_title	str	✓	Label shown when the section is expanded. Defaults to summary.
expanded	bool	✓	Whether the section is open by default.

Style

Authored overlay for Style — all fields optional. Adds CSS shorthand coercers.

Field	Type	Optional	Description
board	BoardStyle	✓	Face-level structural board dimensions.
background	str	✓	Working-surface background color (board and card fills).
accent	str	✓	Accent color token cascaded to sparklines, bars, and focus rings.
muted	str	✓	Muted color token cascaded to spark backgrounds and bar tracks.
font	RootFontStyle	✓	Root font configuration including emoji mode.
border	BorderStyle	✓	Default border style cascaded to all chart cards.
box_shadow	str	✓	CSS box shadow for chart cards; None means no shadow.
opacity	float	✓	Default mark opacity (0–1).
title	TitleStyle	✓	Board and face title style.
text	TextStyle	✓	Markdown and plain text content style.
placeholder	PlaceholderStyle	✓	Placeholder overlay style for empty charts.
charts	ChartsStyle	✓	Root of all chart-type styles and shared chart configuration.
layout	LayoutStyle	✓	Layout container styles (rows, cols, grid, tabs, details).
variables	VariablesStyle	✓	Variable controls chrome style.
page	PageStyle	✓	Page-level canvas style (behind the board).
footer	FooterStyle	✓	Page footer chrome visibility.
timestamp	TimestampStyle	✓	Render-timestamp chrome: visibility, placement, format, and font.
formats	dict[str, str]	✓	Format alias map; None means no aliases at this cascade level.
palettes	dict[str, str]	✓	Theme palette role assignments: open dict mapping role name to palette file name. Default seed: chrome, info, negative, positive, warning, category, sequence, diverge.
roles	dict[str, str]	✓	Optional top-level theme role aliases: bare name → role.alias. e.g. ink: chrome.heading
padding	SpacingValues	✓	Per-face padding override (CSS shorthand or structured).
margin	SpacingValues	✓	Per-face margin override (CSS shorthand or structured).
gap	float	✓	Per-face gap between layout items in pixels.
color	str	✓	Per-face text color override as a CSS color string.

SingleRowBoolProbe

Single-row boolean query probe.

Field	Type	Description
query	str	Name of the query to execute.
column	str	Column in the single result row holding the boolean value.

VariableOptions

Options configuration for variable inputs.

Field	Type	Optional	Description
static	list[str | int | float]	✓	List of static option values (strings or numbers).
query	str	✓	Query name whose result rows provide option values.
column	str	✓	Column in the query result to use as option values.
label_column	str	✓	Column in the query result to use as display labels (separate from values).

FieldConditionalFormatting

Conditional formatting rules scoped to a single column.

Field	Type	Description
when	list[ConditionalRule]	Ordered list of conditional rules. The first matching rule applies; a 'default: true' rule must be last.

ChartSort

Chart-level sort configuration for categorical axes.

Field	Type	Optional	Description
by	str		Column name to sort by.
order	enum: "asc", "desc"	✓	Sort direction (asc or desc).

MultiplesConfig

Small-multiples partition, keyed by layout direction.

Field	Type	Optional	Description
rows	str	✓	Column whose distinct values become vertically stacked panel rows.
columns	str	✓	Column whose distinct values become side-by-side panel columns.
scale	enum: "shared", "independent"	✓	Measure-scale sharing across panels. 'shared' (default) makes panels visually comparable; 'independent' gives each panel its own scale.

ChartDataTable

Container for a chart's data_table block.

Field	Type	Description
entries	list[ChartDataTableSource | ChartDataTableAggregate | ChartDataTablePerSeries]	List of data-table entries (source, aggregate, or per-series rows).

BarChartStyle

Authored overlay for BarChartStyle. Bar chart style: chart-level fields + marks sub-block.

Field	Type	Optional	Description
font	FontStyle	✓	Chart-level font overrides.
aspect_ratio	float	✓	Chart aspect ratio (width/height). Falls back to style.charts.aspect_ratio.
min_height	float	✓	Minimum chart height in pixels. Falls back to style.charts.min_height.
max_height	float	✓	Maximum chart height in pixels. Falls back to style.charts.max_height.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	Chart card border style.
animation_duration	float	✓	Vega-Lite animation duration in milliseconds. Falls back to style.charts.animation_duration.
palette	list[str] | str	✓	Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to style.charts.palette.
single_series_palette	list[str] | str	✓	Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to style.charts.single_series_palette.
legend	LegendStyle	✓	Chart legend style.
tooltip	TooltipStyle	✓	Per-chart-type tooltip style override; None uses the universal style.charts.tooltip.
background	str	✓	Chart-local background color override; None inherits from theme.
color	str | StyleColorConfig	✓	Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
axis	AxisStyle	✓	Override applied to both x and y axes; None inherits the global axis at render.
axis_x	AxisStyle	✓	Per-chart-type x-axis style overrides; None inherits the global axis_x at render.
axis_y	AxisStyle	✓	Per-chart-type y-axis style overrides; None inherits the global axis_y at render.
axis_quantitative	AxisStyle	✓	Per-chart-type quantitative-axis overrides; None inherits the global axis_quantitative at render.
axis_band	AxisStyle	✓	Per-chart-type categorical (band) axis overrides; None inherits the global band axis at render.
number_format	str	✓	Default number format for axes and tooltips (D3 format string); None inherits from theme.
time_format	str	✓	Default time format for temporal axes (D3 time format string); None inherits from theme.
scale	ScaleStyle	✓	Chart-type encoding scale overrides applied to both x and y; None means no override.
data_table	DataTableStyle	✓	Per-chart-type data_table style override. Unset fields fall back to style.charts.data_table.
orientation	enum: "horizontal", "vertical", "auto"	✓	Preferred bar orientation; None uses the renderer default (vertical).
stack	enum: "none", "zero", "normalize", "center"	✓	Default stack mode for bar charts; none renders side-by-side columns.
overlap	float | enum: "auto", "none", "flush", "partial", "full"	✓	Within-group spacing for grouped bars. Keywords: 'auto' (2 series → partial, 3+ → none), 'none' (small gap), 'flush' (bars touch), 'partial' (25% overlap), 'full' (bars coincide). Or a number as a fraction of bar width: >0 overlaps, 0 touches, <0 gaps; 1 is the maximum (bars fully coincide, same as 'full') and values above 1 are clamped to 1 — bars never cross past each other. None uses the renderer default ('auto'). Only applies to grouped bars; setting it together with an active stack mode is an error.
stack_order	enum: "value", "data", "alphabetical"	✓	Z-order of stacked segments. None/'value' puts the largest aggregate at baseline. 'data' follows SQL row order (orientation-stable not guaranteed). 'alphabetical' sorts by color column name. Ignored when stacking is off or no color.
endpoint_labels	EndpointLabelsConfig	✓	Endpoint label pane configuration for bar charts.
marks	BarChartMarksStyle	✓	Bar-family mark overrides. Unset fields fall back to style.charts.marks.

LineChartStyle

Authored overlay for LineChartStyle. Line chart style: chart-level fields + marks sub-block.

Field	Type	Optional	Description
font	FontStyle	✓	Chart-level font overrides.
aspect_ratio	float	✓	Chart aspect ratio (width/height). Falls back to style.charts.aspect_ratio.
min_height	float	✓	Minimum chart height in pixels. Falls back to style.charts.min_height.
max_height	float	✓	Maximum chart height in pixels. Falls back to style.charts.max_height.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	Chart card border style.
animation_duration	float	✓	Vega-Lite animation duration in milliseconds. Falls back to style.charts.animation_duration.
palette	list[str] | str	✓	Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to style.charts.palette.
single_series_palette	list[str] | str	✓	Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to style.charts.single_series_palette.
legend	LegendStyle	✓	Chart legend style.
tooltip	TooltipStyle	✓	Per-chart-type tooltip style override; None uses the universal style.charts.tooltip.
background	str	✓	Chart-local background color override; None inherits from theme.
color	str | StyleColorConfig	✓	Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
axis	AxisStyle	✓	Override applied to both x and y axes; None inherits the global axis at render.
axis_x	AxisStyle	✓	Per-chart-type x-axis style overrides; None inherits the global axis_x at render.
axis_y	AxisStyle	✓	Per-chart-type y-axis style overrides; None inherits the global axis_y at render.
axis_quantitative	AxisStyle	✓	Per-chart-type quantitative-axis overrides; None inherits the global axis_quantitative at render.
axis_band	AxisStyle	✓	Per-chart-type categorical (band) axis overrides; None inherits the global band axis at render.
number_format	str	✓	Default number format for axes and tooltips (D3 format string); None inherits from theme.
time_format	str	✓	Default time format for temporal axes (D3 time format string); None inherits from theme.
scale	ScaleStyle	✓	Chart-type encoding scale overrides applied to both x and y; None means no override.
data_table	DataTableStyle	✓	Per-chart-type data_table style override. Unset fields fall back to style.charts.data_table.
endpoint_labels	EndpointLabelsConfig	✓	Endpoint label pane configuration for line charts.
marks	LineChartMarksStyle	✓	Line-family mark overrides. Unset fields fall back to style.charts.marks.

AreaChartStyle

Authored overlay for AreaChartStyle. Area chart style: chart-level fields + marks sub-block.

Field	Type	Optional	Description
font	FontStyle	✓	Chart-level font overrides.
aspect_ratio	float	✓	Chart aspect ratio (width/height). Falls back to style.charts.aspect_ratio.
min_height	float	✓	Minimum chart height in pixels. Falls back to style.charts.min_height.
max_height	float	✓	Maximum chart height in pixels. Falls back to style.charts.max_height.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	Chart card border style.
animation_duration	float	✓	Vega-Lite animation duration in milliseconds. Falls back to style.charts.animation_duration.
palette	list[str] | str	✓	Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to style.charts.palette.
single_series_palette	list[str] | str	✓	Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to style.charts.single_series_palette.
legend	LegendStyle	✓	Chart legend style.
tooltip	TooltipStyle	✓	Per-chart-type tooltip style override; None uses the universal style.charts.tooltip.
background	str	✓	Chart-local background color override; None inherits from theme.
color	str | StyleColorConfig	✓	Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
axis	AxisStyle	✓	Override applied to both x and y axes; None inherits the global axis at render.
axis_x	AxisStyle	✓	Per-chart-type x-axis style overrides; None inherits the global axis_x at render.
axis_y	AxisStyle	✓	Per-chart-type y-axis style overrides; None inherits the global axis_y at render.
axis_quantitative	AxisStyle	✓	Per-chart-type quantitative-axis overrides; None inherits the global axis_quantitative at render.
axis_band	AxisStyle	✓	Per-chart-type categorical (band) axis overrides; None inherits the global band axis at render.
number_format	str	✓	Default number format for axes and tooltips (D3 format string); None inherits from theme.
time_format	str	✓	Default time format for temporal axes (D3 time format string); None inherits from theme.
scale	ScaleStyle	✓	Chart-type encoding scale overrides applied to both x and y; None means no override.
data_table	DataTableStyle	✓	Per-chart-type data_table style override. Unset fields fall back to style.charts.data_table.
stack	enum: "none", "zero", "normalize", "center"	✓	Default stack mode for area charts: 'none', 'zero', 'normalize', or 'center'.
endpoint_labels	EndpointLabelsConfig	✓	Endpoint label pane configuration for area charts.
marks	AreaChartMarksStyle	✓	Area-family mark overrides. Unset fields fall back to style.charts.marks.

ScatterChartStyle

Authored overlay for ScatterChartStyle. Scatter chart style: chart-level fields + marks sub-block.

Field	Type	Optional	Description
font	FontStyle	✓	Chart-level font overrides.
aspect_ratio	float	✓	Chart aspect ratio (width/height). Falls back to style.charts.aspect_ratio.
min_height	float	✓	Minimum chart height in pixels. Falls back to style.charts.min_height.
max_height	float	✓	Maximum chart height in pixels. Falls back to style.charts.max_height.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	Chart card border style.
animation_duration	float	✓	Vega-Lite animation duration in milliseconds. Falls back to style.charts.animation_duration.
palette	list[str] | str	✓	Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to style.charts.palette.
single_series_palette	list[str] | str	✓	Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to style.charts.single_series_palette.
legend	LegendStyle	✓	Chart legend style.
tooltip	TooltipStyle	✓	Per-chart-type tooltip style override; None uses the universal style.charts.tooltip.
background	str	✓	Chart-local background color override; None inherits from theme.
color	str | StyleColorConfig	✓	Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
axis	AxisStyle	✓	Override applied to both x and y axes; None inherits the global axis at render.
axis_x	AxisStyle	✓	Per-chart-type x-axis style overrides; None inherits the global axis_x at render.
axis_y	AxisStyle	✓	Per-chart-type y-axis style overrides; None inherits the global axis_y at render.
axis_quantitative	AxisStyle	✓	Per-chart-type quantitative-axis overrides; None inherits the global axis_quantitative at render.
axis_band	AxisStyle	✓	Per-chart-type categorical (band) axis overrides; None inherits the global band axis at render.
number_format	str	✓	Default number format for axes and tooltips (D3 format string); None inherits from theme.
time_format	str	✓	Default time format for temporal axes (D3 time format string); None inherits from theme.
scale	ScaleStyle	✓	Chart-type encoding scale overrides applied to both x and y; None means no override.
data_table	DataTableStyle	✓	Per-chart-type data_table style override. Unset fields fall back to style.charts.data_table.
marks	ScatterChartMarksStyle	✓	Scatter-family mark overrides. Unset fields fall back to style.charts.marks.

HeatmapChartStyle

Authored overlay for HeatmapChartStyle. Heatmap chart style.

Field	Type	Optional	Description
font	FontStyle	✓	Chart-level font overrides.
aspect_ratio	float	✓	Chart aspect ratio (width/height). Falls back to style.charts.aspect_ratio.
min_height	float	✓	Minimum chart height in pixels. Falls back to style.charts.min_height.
max_height	float	✓	Maximum chart height in pixels. Falls back to style.charts.max_height.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	Chart card border style.
animation_duration	float	✓	Vega-Lite animation duration in milliseconds. Falls back to style.charts.animation_duration.
palette	list[str] | str	✓	Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to style.charts.palette.
single_series_palette	list[str] | str	✓	Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to style.charts.single_series_palette.
legend	LegendStyle	✓	Chart legend style.
tooltip	TooltipStyle	✓	Per-chart-type tooltip style override; None uses the universal style.charts.tooltip.
background	str	✓	Chart-local background color override; None inherits from theme.
color	str | StyleColorConfig	✓	Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
axis	AxisStyle	✓	Override applied to both x and y axes; None inherits the global axis at render.
axis_x	AxisStyle	✓	Per-chart-type x-axis style overrides; None inherits the global axis_x at render.
axis_y	AxisStyle	✓	Per-chart-type y-axis style overrides; None inherits the global axis_y at render.
axis_quantitative	AxisStyle	✓	Per-chart-type quantitative-axis overrides; None inherits the global axis_quantitative at render.
axis_band	AxisStyle	✓	Per-chart-type categorical (band) axis overrides; None inherits the global band axis at render.
number_format	str	✓	Default number format for axes and tooltips (D3 format string); None inherits from theme.
time_format	str	✓	Default time format for temporal axes (D3 time format string); None inherits from theme.
scale	ScaleStyle	✓	Chart-type encoding scale overrides applied to both x and y; None means no override.
data_table	DataTableStyle	✓	Per-chart-type data_table style override. Unset fields fall back to style.charts.data_table.
cell_padding	float	✓	Padding between heatmap cells in pixels.
color_scheme	str	✓	Color scheme name for heatmap gradient (e.g. 'blues', 'viridis').
marks	HeatmapChartMarksStyle	✓	Heatmap-family mark overrides. Unset fields fall back to style.charts.marks.

ChartTotal

Donut center total — auto-rendered sum at the center of a donut, with author override.

Field	Type	Optional	Description
visible	bool	✓	Whether to render the donut center total. Defaults True; set False to suppress the auto-rendered center on donuts whose theta values aren't a meaningful sum (e.g. pre-aggregated percentage shares).
label	str	✓	Caption text displayed below the center total value.
format	str | FormatConfig	✓	Number format (D3 spec, preset, or FormatConfig).

PieChartStyle

Authored overlay for PieChartStyle. Pie/donut chart style: geometry + total (flat) + marks sub-block.

Field	Type	Optional	Description
font	FontStyle	✓	Chart-level font overrides.
aspect_ratio	float	✓	Aspect ratio (width/height) of the pie chart viewport.
min_height	float	✓	Minimum chart height in pixels. Falls back to style.charts.min_height.
max_height	float	✓	Maximum chart height in pixels. Falls back to style.charts.max_height.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	Chart card border style.
animation_duration	float	✓	Vega-Lite animation duration in milliseconds. Falls back to style.charts.animation_duration.
palette	list[str] | str	✓	Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to style.charts.palette.
single_series_palette	list[str] | str	✓	Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to style.charts.single_series_palette.
legend	LegendStyle	✓	Chart legend style.
tooltip	TooltipStyle	✓	Per-chart-type tooltip style override; None uses the universal style.charts.tooltip.
background	str	✓	Chart-local background color override; None inherits from theme.
color	str | StyleColorConfig	✓	Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
inner_radius	float	✓	Hole-to-disk ratio 0–1 (inner radius / outer radius). None = solid pie (no hole).
total	TotalStyle	✓	Donut center total paint (value and label).
marks	PieChartMarksStyle	✓	Pie-family mark overrides. Unset fields fall back to style.charts.marks.

KpiSupportConfig

Support-line block authored alongside a KPI's main value.

Field	Type	Optional	Description
value	str	✓	Column reference (string column name) for the support number/text.
label	str	✓	Trailing explainer text rendered beside the support value.
format	str | FormatConfig	✓	Number format (D3 spec, preset, or FormatConfig).
glyph	str	✓	Optional prefix glyph (e.g. '▲', '▼', '●').
tone	enum: "positive", "negative", "warning"	✓	Semantic styling for the support value/glyph.

KpiChartStyle

Authored overlay for KpiChartStyle. Produced by cascade from theme YAML.

Field	Type	Optional	Description
font	FontStyle	✓	KPI chart-level font overrides. Unset fields fall back to style.charts.font.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	KPI card border style.
animation_duration	float	✓	Vega-Lite animation duration in milliseconds. Falls back to style.charts.animation_duration.
palette	list[str] | str	✓	Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to style.charts.palette.
single_series_palette	list[str] | str	✓	Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to style.charts.single_series_palette.
legend	LegendStyle	✓	Chart legend style.
tooltip	TooltipStyle	✓	Per-chart-type tooltip style override; None uses the universal style.charts.tooltip.
background	str	✓	Chart-local background color override; None inherits from theme.
color	str | StyleColorConfig	✓	Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
value	KpiValueStyle	✓	KPI headline value slot.
label	KpiSlotStyle	✓	KPI card label slot.
affix	KpiSlotStyle	✓	Currency/percent affix slot.
glyph	KpiSlotStyle	✓	Indicator glyph (▲▼●) slot.
min_card_width	float	✓	Minimum KPI card width in pixels.
default_width	float	✓	Default KPI card width in pixels.
default_height	float	✓	Default KPI card height in pixels.
content_padding	SpacingValues	✓	Inner inset (top/right/bottom/left) for KPI card content in pixels.
tones	KpiTonesStyle	✓	Semantic tone color palette for KPI values and glyphs.
tone	str	✓	Semantic tone selector (positive | negative | warning). None = default chrome.

TableChartStyle

Authored overlay for TableChartStyle. Table chart style overrides layered on top of shared chart defaults.

Field	Type	Optional	Description
font	FontStyle	✓	Table chart-level font overrides. Unset fields fall back to style.charts.font.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	Table outer border style.
animation_duration	float	✓	Vega-Lite animation duration in milliseconds. Falls back to style.charts.animation_duration.
palette	list[str] | str	✓	Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to style.charts.palette.
single_series_palette	list[str] | str	✓	Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to style.charts.single_series_palette.
legend	LegendStyle	✓	Chart legend style.
tooltip	TooltipStyle	✓	Per-chart-type tooltip style override; None uses the universal style.charts.tooltip.
background	str	✓	Table background color; None inherits from theme.
color	str | StyleColorConfig	✓	Table text color override (CSS string) or gradient scale config; None uses the theme default.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
rule	TableRuleStyle	✓	Table rule style overrides (color). None = no override; inherits from theme.
outer_padding	float	✓	Outer table padding in pixels.
bottom_padding	float	✓	Extra bottom padding below the last row in pixels.
column_layout	TableColumnsStyle	✓	Default column width and cell padding settings.
header	TableHeaderStyle	✓	Table header row style.
row	TableRowStyle	✓	Table body row style.
row_numbers	TableRowNumbersStyle	✓	Leading row-number column configuration.
title_row	TableTitleStyle	✓	Table title row style.
wrap	bool	✓	Allow cell text wrapping; false clips to single line.
pagination	PaginationConfig	✓	Client-side pagination defaults for table charts.
column_defaults	TableColumnDefaultsConfig	✓	Table-level column defaults applied to every column; None means no defaults authored.
columns	dict[str, TableColumnConfig]	✓	Per-column display configuration keyed by column name (label, format, width, etc.).
header_overflow	enum: "clip", "truncate", "wrap-two", "wrap"	✓	Table column header text overflow mode; None inherits from theme.
paginator	PaginatorStyle	✓	Visual style for the paginator control (chevrons + page numbers).
symbol_mode	str	✓	Where to show currency-prefix and magnitude/unit suffix symbols in a numeric column. 'all' shows the full formatted value on every row; 'anchors' shows it only on the first data row and summary/total rows, stripping prefix and suffix from plain middle rows so the anchors guide the reader at the top and bottom of the value field.
more_rows	TableEdgeStyle	✓	Style for the 'more rows' edge-case indicator.
empty_state	TableEdgeStyle	✓	Style for the empty-state (no data) indicator.
spark	SparkStyle	✓	Inline sparkline defaults for table cells.
transpose	bool	✓	When True, render a single wide data row as N (label, value) rows — one per column. Raises ChartDataError when data has more than one row. Used for Looker single-value summary tiles with multiple measures.
text_baseline_offset	float	✓	Vertical offset to align SVG text baseline with cell grid in pixels.
title_baseline_offset	float	✓	Vertical offset to align SVG title baseline in pixels.
title_subtitle_gap	float	✓	Gap between table title and subtitle lines in pixels.
subtitle	SubtitleStyle	✓	Table subtitle font-sizing constants.

BasemapConfig

Tile-layer configuration for point_map and bubble_map charts.

Field	Type	Optional	Description
type	str	✓	Tile provider type (e.g. 'mapbox', 'raster').
style	str	✓	Tile style URL (e.g. Mapbox style URI).
source	str	✓	Named geographic boundary source (e.g. 'us-states') for overlay rendering.
attribution	str	✓	Attribution text for the tile provider.
fill	str	✓	Fill color for geographic boundary overlay.
stroke	str	✓	Stroke color for geographic boundary overlay.

PointMapChartStyle

Authored overlay for PointMapChartStyle. Point map chart style.

Field	Type	Optional	Description
font	FontStyle	✓	Chart-level font overrides.
aspect_ratio	float	✓	Chart aspect ratio (width/height). Falls back to style.charts.aspect_ratio.
min_height	float	✓	Minimum chart height in pixels. Falls back to style.charts.min_height.
max_height	float	✓	Maximum chart height in pixels. Falls back to style.charts.max_height.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	Chart card border style.
animation_duration	float	✓	Vega-Lite animation duration in milliseconds. Falls back to style.charts.animation_duration.
palette	list[str] | str	✓	Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to style.charts.palette.
single_series_palette	list[str] | str	✓	Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to style.charts.single_series_palette.
legend	LegendStyle	✓	Chart legend style.
tooltip	TooltipStyle	✓	Per-chart-type tooltip style override; None uses the universal style.charts.tooltip.
background	str	✓	Chart-local background color override; None inherits from theme.
color	str | StyleColorConfig	✓	Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
projection	ProjectionStyle	✓	Vega-Lite projection configuration for this geo family.
basemap	BasemapStyle	✓	Background map layer; None source = no topo layer.
marks	PointMapChartMarksStyle	✓	Point-map-family mark overrides. Unset fields fall back to style.charts.marks.

GeoshapeChartStyle

Authored overlay for GeoshapeChartStyle. Geoshape (choropleth) chart style.

Field	Type	Optional	Description
font	FontStyle	✓	Chart-level font overrides.
aspect_ratio	float	✓	Chart aspect ratio (width/height). Falls back to style.charts.aspect_ratio.
min_height	float	✓	Minimum chart height in pixels. Falls back to style.charts.min_height.
max_height	float	✓	Maximum chart height in pixels. Falls back to style.charts.max_height.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	Chart card border style.
animation_duration	float	✓	Vega-Lite animation duration in milliseconds. Falls back to style.charts.animation_duration.
palette	list[str] | str	✓	Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to style.charts.palette.
single_series_palette	list[str] | str	✓	Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to style.charts.single_series_palette.
legend	LegendStyle	✓	Chart legend style.
tooltip	TooltipStyle	✓	Per-chart-type tooltip style override; None uses the universal style.charts.tooltip.
background	str	✓	Chart-local background color override; None inherits from theme.
color	str | StyleColorConfig	✓	Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
projection	ProjectionStyle	✓	Vega-Lite projection configuration for this geo family.
basemap	BasemapStyle	✓	Background map layer; None source = no topo layer.
color_scheme	str	✓	Color scheme name for choropleth gradient.
marks	GeoshapeChartMarksStyle	✓	Geoshape-family mark overrides. Unset fields fall back to style.charts.marks.

Layer

A single layer in a layered chart authored YAML.

Field	Type	Optional	Description
type	enum: "bar", "line", "area", "circle", "square", "tick", "rule", "trail", "rect", "image", "scatter"		Mark type for this layer (bar, line, area, circle, square, tick, rule, trail, rect, image, scatter).
query	str	✓	Query name for this layer's data (overrides chart-level query).
x	str	✓	X-axis column name for this layer.
y	str	✓	Y-axis column name for this layer.
label	str	✓	Label column name for this layer.
color	str	✓	Color data channel for this layer: bare column name only.
axis_y	LayerAxisYStyle	✓	Y-axis settings for this layer (orientation, title).

FormatConfig

Format configuration for value display.

Field	Type	Optional	Description
spec	str	✓	D3 format string (e.g., ',.0f'), preset name (e.g., 'currency'), or Excel pattern.
prefix	str	✓	Custom prefix prepended to the formatted value (e.g., '$').
suffix	str	✓	Custom suffix appended to the formatted value (e.g., ' USD', '%').
notation	enum: "analytic", "narrative"	✓	Notation style: 'analytic' for SI-prefix (1 B, 1 M) or 'narrative' for prose-style (1bn, 1mn).

LayeredChartStyle

Flat style patch for layered multi-mark charts.

Field	Type	Optional	Description
font	FontStyle	✓	Chart-level font overrides.
aspect_ratio	float	✓	Chart aspect ratio (width/height). Falls back to style.charts.aspect_ratio.
min_height	float	✓	Minimum chart height in pixels. Falls back to style.charts.min_height.
max_height	float	✓	Maximum chart height in pixels. Falls back to style.charts.max_height.
padding	PaddingStyle	✓	Chart inner padding overrides.
border	BorderStyle	✓	Chart card border style.
animation_duration	float	✓	Vega-Lite animation duration in milliseconds. Falls back to style.charts.animation_duration.
palette	list[str] | str	✓	Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to style.charts.palette.
single_series_palette	list[str] | str	✓	Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to style.charts.single_series_palette.
legend	LegendStyle	✓	Chart legend style overrides.
tooltip	TooltipStyle	✓	Chart tooltip style overrides.
background	str	✓	Chart-local background color override; None inherits from theme.
color	str | StyleColorConfig	✓	Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
axis	AxisStyle	✓	Override applied to both x and y axes; None inherits the global axis at render.
axis_x	AxisStyle	✓	Per-chart-type x-axis style overrides; None inherits the global axis_x at render.
axis_y	AxisStyle	✓	Per-chart-type y-axis style overrides; None inherits the global axis_y at render.
axis_quantitative	AxisStyle	✓	Per-chart-type quantitative-axis overrides; None inherits the global axis_quantitative at render.
axis_band	AxisStyle	✓	Per-chart-type categorical (band) axis overrides; None inherits the global band axis at render.
number_format	str	✓	Default number format for axes and tooltips (D3 format string); None inherits from theme.
time_format	str	✓	Default time format for temporal axes (D3 time format string); None inherits from theme.
scale	ScaleStyle	✓	Chart-type encoding scale overrides applied to both x and y; None means no override.
data_table	DataTableStyle	✓	Per-chart-type data_table style override. Unset fields fall back to style.charts.data_table.
orientation	enum: "horizontal", "vertical", "auto"	✓	Preferred bar orientation; None uses the renderer default (vertical).
stack	enum: "none", "zero", "normalize", "center"	✓	Default stack mode for bar/area charts.
stack_order	enum: "value", "data", "alphabetical"	✓	Z-order of stacked segments.
endpoint_labels	EndpointLabelsConfig	✓	Endpoint label pane configuration.
marks	LayeredMarksStyle	✓	Per-mark-type style overrides (bar/line/area/point).

CalloutChartStyle

Authored overlay for CalloutChartStyle. Chart-family style for type: callout charts and runtime chart-error fallback cards.

Field	Type	Optional	Description
tone	str	✓	Semantic tone for palette-role lookup (info | positive | negative | warning).
background	str	✓	Callout card background color (info.bg default).
border	BorderStyle	✓	Callout card border style.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
section_gap	float	✓	Vertical gap between callout title and message in pixels.
title	CalloutElementStyle	✓	Callout title element style.
message	CalloutElementStyle	✓	Callout message element style.

SparkBarChartStyle

Authored overlay for SparkBarChartStyle. Produced by cascade from theme YAML.

Field	Type	Optional	Description
default_width	float	✓	Default spark_bar chart width in pixels.
min_width	float	✓	Minimum spark_bar chart width in pixels.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
bar	SparkBarBarStyle	✓	Bar geometry (height, padding, color).
label	SparkBarChartLabelStyle	✓	Category-label column (visibility, reserved width).
count	SparkBarCountStyle	✓	Count-value column (visibility, reserved width).
max_bars	int	✓	Maximum number of bars to render.
font	FontStyle	✓	Spark_bar font style overrides. Unset fields fall back to style.charts.font.
border	BorderStyle	✓	Spark_bar outer border style.
subtitle	SubtitleStyle	✓	Spark_bar subtitle font-sizing constants.

ForeachConfig

foreach loop configuration.

Field	Type	Description
query	ForeachQuery	Inline data source providing the rows to iterate over.
as	str	Variable name bound to each row (accessible as {{ as.field }}).
items	list[str | Face | BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | LayeredChart | CalloutChart | SparkBarChart | ForeachItem | dict[str, BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | LayeredChart | CalloutChart | SparkBarChart]]	Layout item templates resolved once per data row.

GridItem

Grid layout item with position and span.

Field	Type	Optional	Description
item	str | Face | BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | LayeredChart | CalloutChart | SparkBarChart | ForeachItem | dict[str, BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | LayeredChart | CalloutChart | SparkBarChart]		Chart name or inline chart/face definition to place in this grid cell.
col	int	✓	Column position (0-indexed). Auto-placed if omitted.
row	int	✓	Row position (0-indexed). Auto-placed if omitted.
col_span	int	✓	Number of columns to span (width in grid units).
row_span	int	✓	Number of rows to span (height in grid units).
width	int	✓	Alias for col_span (more intuitive name).
height	int	✓	Alias for row_span (more intuitive name).
description	str	✓	Optional metadata for AI search and context tooltips.

TabItem

Tab layout item.

Field	Type	Optional	Description
title	str		Tab label displayed in the tab bar.
icon	str	✓	Optional icon shown in the tab (e.g., emoji or icon name).
description	str	✓	Optional metadata for AI search and context tooltips.
text	str	✓	Markdown text content shown in this tab.
style	Style	✓	Style patch for this tab's content area.
rows	list[str | Face | BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | LayeredChart | CalloutChart | SparkBarChart | ForeachItem | dict[str, BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | LayeredChart | CalloutChart | SparkBarChart]]	✓	Vertical stack layout for this tab's content.
cols	list[str | Face | BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | LayeredChart | CalloutChart | SparkBarChart | ForeachItem | dict[str, BarChart | LineChart | AreaChart | ScatterChart | HeatmapChart | PieChart | KpiChart | TableChart | PointMapChart | GeoshapeChart | LayeredChart | CalloutChart | SparkBarChart]]	✓	Horizontal layout for this tab's content.
grid	GridLayout	✓	CSS-grid layout for this tab's content.
tabs	TabLayout	✓	Nested tab layout (tabs within tabs).

BoardStyle

Authored overlay for BoardStyle. Face-level structural dimensions. Do NOT cascade to child faces.

Field	Type	Optional	Description
width	float	✓	Board width in pixels.
min_height	float	✓	Minimum board height in pixels.
margin	float	✓	Board outer margin in pixels.
card_padding	float	✓	Padding added to each card side in pixels.
card_gap	float	✓	Gap between cards in pixels.

RootFontStyle

Authored overlay for RootFontStyle. Root-level font configuration: FontStyle fields plus a required emoji mode.

Field	Type	Optional	Description
family	str	✓	Font family name (e.g., 'sans-serif', 'Roboto').
color	str	✓	Text color as a CSS color string.
size	float	✓	Font size in pixels.
weight	str | float	✓	Font weight (e.g., 'bold', 400, 700).
style	enum: "normal", "italic"	✓	Font style (normal or italic).
decoration	enum: "none", "line-through", "underline"	✓	Text decoration (underline, line-through, or none).
case	enum: "none", "sentence", "title", "upper", "lower", "slug", "camel"	✓	Letter-case transform applied at render time. 'title' uses Chicago/Gruber rules and preserves tokens with internal capitals (ARR, iPhone). 'sentence' uppercases only the first character. 'none' (default) emits the string without any letter-case change.
line_height	float	✓	Line height as a unitless multiple of font size. Cascades through Style.font to all text roles that carry a FontStyle slot. Body prose defaults to 1.25; titles override tighter via their font patch in theme YAML.
emoji	enum: "monochrome", "color", "system-default", "disabled"	✓	Emoji rendering mode for the dashboard font stack.

BorderStyle

Box border. Does NOT cascade (ADR-003: box properties reset per level).

Field	Type	Optional	Description
radius	float	✓	Border corner radius in pixels.
color	str	✓	Border color (CSS color string).
width	float	✓	Border width in pixels.

TitleStyle

Authored overlay for TitleStyle. Board and face titles.

Field	Type	Optional	Description
font	FontStyle	✓	Title font style overrides. Unset fields fall back to style.font.
sizes	list[float]	✓	Font sizes for the H1–H6 heading ramp, indexed by face.level - 1. Face/prose titles index this ramp directly (no width input). Object titles (chart/table/spark) combine width_offsets with a fixed object-title anchor to pick a slot.
width_offsets	TitleWidthOffsetsStyle	✓	Additive level offsets by card width (tiny/narrow/medium/wide). Consumed by chart_title_spec only — object titles add the tier offset to a fixed anchor to pick an H slot from sizes. Face/prose titles are level-only and do not consult these.
min_height	float	✓	Minimum title row height in pixels.
overflow	str	✓	Text overflow mode (clip, truncate, wrap-two, wrap).
position	TitlePositionStyle	✓	Vega-Lite title positioning: anchor, angle, offset, baseline.
level	int | enum: "auto"	✓	Heading level override for face titles. 'auto' (default) computes the level semantically as the count of titled ancestors. An integer value locks all titles in this face and its descendants to that H-level.
subtitle	TitleSubtitleStyle	✓	Subtitle font styles.

TextStyle

Authored overlay for TextStyle. Markdown / plain text content.

Field	Type	Optional	Description
font	FontStyle	✓	Text font style overrides. Unset fields fall back to style.font.
align	enum: "left", "center", "right"	✓	Text alignment for the face body-text block.
paragraph	BlockMarginStyle	✓	Spacing above/below each paragraph block (in line-height units).
heading	BlockMarginStyle	✓	Spacing above/below heading blocks (H1–H6) in line-height units.
column	TextColumnStyle	✓	Multi-column layout for the face body-text block.
code	TextCodeStyle	✓	Inline + fenced code box styling (font, background, border).
blockquote	TextBlockquoteStyle	✓	Blockquote box styling (font, background, border/left-rule).

PlaceholderStyle

Authored overlay for PlaceholderStyle.

Field	Type	Optional	Description
opacity	float	✓	Opacity of the placeholder overlay (0–1).
overlay	PlaceholderOverlay	✓	Overlay text and background style.

ChartsStyle

Authored overlay for ChartsStyle. Registry of all chart-type styles plus shared chart configuration.

Field	Type	Optional	Description
font	FontStyle	✓	Chart-level font overrides. Unset fields fall back to style.font.
aspect_ratio	float	✓	Chart aspect ratio (width/height).
min_height	float	✓	Minimum chart height in pixels.
max_height	float	✓	Maximum chart height in pixels.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels.
border	BorderStyle	✓	Chart card border style.
animation_duration	float	✓	Vega-Lite animation duration in milliseconds.
palette	list[str] | str	✓	Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time.
single_series_palette	list[str] | str	✓	Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order.
legend	LegendStyle	✓	Chart legend style.
tooltip	TooltipStyle	✓	Chart tooltip style.
background	str	✓	Chart canvas background; None inherits from the board background via apply_inherit. Falls back to style.background.
color	str | StyleColorConfig	✓	Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
dashes	list[list[int]]	✓	Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission.
default_width	float	✓	Default chart width in pixels when no explicit width is set.
default_chart_height	float	✓	Fallback chart height in pixels when aspect-ratio sizing is unavailable.
default_table_height	float	✓	Placeholder table height in pixels; replaced by data-aware row-count sizing at render time.
label_usable_ratio	float	✓	Fraction of chart width usable for axis labels (0–1); labels are tilted when full labels exceed this width.
axis	AxisStyle	✓	Shared axis style applied to all axes before per-axis overrides.
axis_x	AxisStyle	✓	X-axis style overrides applied after the shared axis. Unset fields fall back to style.charts.axis.
axis_y	AxisStyle	✓	Y-axis style overrides applied after the shared axis. Unset fields fall back to style.charts.axis.
axis_quantitative	AxisStyle	✓	Quantitative axis style overrides applied after axis_x/axis_y. Unset fields fall back to style.charts.axis.
view	ViewStyle	✓	Vega-Lite view dimensions and border.
autosize	AutosizeStyle	✓	Vega-Lite autosize configuration.
marks	GlobalMarksStyle	✓	Global mark defaults (tier-1 of the marks cascade).
bar	BarChartStyle	✓	Bar chart style.
line	LineChartStyle	✓	Line chart style.
area	AreaChartStyle	✓	Area chart style.
scatter	ScatterChartStyle	✓	Scatter chart style.
histogram	HistogramChartStyle	✓	Histogram chart style.
heatmap	HeatmapChartStyle	✓	Heatmap chart style.
geoshape	GeoshapeChartStyle	✓	Geoshape (choropleth) chart style.
point_map	PointMapChartStyle	✓	Point map chart style.
pie	PieChartStyle	✓	Pie/donut chart style.
series_label	SeriesLabelStyle	✓	Shared series-label typography for endpoint labels, stack labels, and slice callouts.
kpi	KpiChartStyle	✓	KPI card chart style.
table	TableChartStyle	✓	Table chart style.
spark_bar	SparkBarChartStyle	✓	Spark_bar (full-chart horizontal bar) style.
data_table	DataTableStyle	✓	Attached data_table strip style.
callout	CalloutChartStyle	✓	Callout chart-family style for type:callout and runtime fallback cards.

LayoutStyle

Authored overlay for LayoutStyle.

Field	Type	Optional	Description
rows	LayoutGapStyle	✓	Row layout gap configuration.
cols	LayoutGapStyle	✓	Column layout gap configuration.
grid	GridLayoutStyle	✓	Grid layout configuration.
tabs	TabsStyle	✓	Tabs layout style.
details	DetailsStyle	✓	Details (accordion) layout style.

VariablesStyle

Authored overlay for VariablesStyle. Variable controls chrome styling.

Field	Type	Optional	Description
visible	bool	✓	Show the variables control panel.
position	enum: "top", "bottom", "title-inline"	✓	Variables strip placement: stacked under the title (top/bottom) or on one horizontal band with the face title (title-inline).
title_inline_band_bottom_pad	float	✓	Bottom padding in pixels added below the title-inline band.
gap	float	✓	Gap between variable controls in pixels.
label_position	str	✓	Position of labels relative to their input controls (e.g. 'left', 'top').
title_inline_title_max_width	float	✓	When position is title-inline: max title column width in px. 0 means no cap (title uses remaining width after reserving space for variables).
font	FontStyle	✓	Variables panel base font style overrides. Unset fields fall back to style.font.
label	VariablesLabelStyle	✓	Variable label typography.
value	VariablesValueStyle	✓	Variable value typography.
placeholder	VariablesPlaceholderStyle	✓	Style for unselected/hint text in variable inputs.
line_height	float	✓	Line height for variable control text in pixels.
padding	float	✓	Outer padding around the variables panel in pixels.
container_height	float	✓	Height of the variables panel container in pixels.
container_padding	float	✓	Inner padding of the variables panel container in pixels.
border	BorderStyle	✓	Variables panel border style.
control_gap	float	✓	Gap between label and input within a single control in pixels.
input	InputStyle	✓	Input control style.
popover_rail_background	str	✓	Background color for the preset rail (left column) inside the daterange chip's popover. Typically the theme's surface-subtle step — gray-50 on white-canvas themes, a cream-toned light on warm-canvas themes. Distinct from the popover card itself, which is always white-equivalent.

PageStyle

Authored overlay for PageStyle. Page-level (outer HTML canvas) styling.

Field	Type	Optional	Description
background	str	✓	Page canvas background color (behind the face board).

FooterStyle

Authored overlay for FooterStyle. Page footer chrome: visibility, attribution text, font, and rule.

Field	Type	Optional	Description
visible	bool	✓	Show the footer attribution line.
text	str	✓	Attribution text shown in the footer.
link	str	✓	URL the footer brand word 'dataface' links to; null renders plain text.
font	FontStyle	✓	Footer text font style (size and color required).
y_offset	float	✓	Vertical offset from bottom edge in pixels.
rule	FooterRule	✓	Hairline rule above footer text; null disables the rule.

TimestampStyle

Authored overlay for TimestampStyle. Authored timestamp chrome: visibility, placement, strftime format, font, and y-offset.

Field	Type	Optional	Description
visible	bool	✓	Show the render-timestamp line.
position	enum: "top", "footer"	✓	Timestamp row: top page chrome or footer baseline.
align	enum: "left", "right"	✓	Timestamp horizontal alignment within its row.
format	str	✓	strftime format string for the render timestamp.
y	float	✓	Y-coordinate for top-positioned timestamp in pixels.
font	FontStyle	✓	Timestamp font style overrides (size, color, weight, ...).

SpacingValues

Pre-parsed CSS spacing (margin/padding).

Field	Type	Optional	Description
top	float	✓	Top spacing in pixels.
right	float	✓	Right spacing in pixels.
bottom	float	✓	Bottom spacing in pixels.
left	float	✓	Left spacing in pixels.

ConditionalRule

A single conditional formatting rule.

Field	Type	Optional	Description
eq	Any	✓	Match rows where the column value equals this value.
ne	Any	✓	Match rows where the column value does not equal this value.
lt	int | float	✓	Match rows where the column value is less than this number.
lte	int | float	✓	Match rows where the column value is less than or equal to this number.
gt	int | float	✓	Match rows where the column value is greater than this number.
gte	int | float	✓	Match rows where the column value is greater than or equal to this number.
between	list[int | float]	✓	Match rows where the column value falls in [low, high] (inclusive).
in	list[Any]	✓	Match rows where the column value is in this list.
is_null	bool	✓	Match null rows (true) or non-null rows (false).
default	enum: "True"	✓	Catch-all rule that matches any row not matched by earlier rules. Must be the last entry.
background	str	✓	Cell background color applied when the rule matches.
font	FontStyle	✓	Font style overrides (color, weight, style, decoration) applied when the rule matches.
glyph	str	✓	Glyph character prepended to the cell value when the rule matches.
glyph_color	str	✓	Color for the glyph when the rule matches. Requires glyph to be set.

ChartDataTableSource

A data_table row that reads a column's raw per-x value.

Field	Type	Optional	Description
source	str		Query column the row reads from (per-x raw value).
format	str | FormatConfig	✓	D3 format string or format config object. Optional; inherits the chart measure format when omitted and source matches chart.y.
label	str	✓	Left-stub row label. Optional.

ChartDataTableAggregate

A data_table row that reads an aggregate of a column grouped by x.

Field	Type	Optional	Description
aggregate	enum: "sum", "avg", "min", "max", "median", "count", "count_distinct"		Aggregate operation applied per x-group. One of: sum, avg, min, max, median, count, count_distinct. Exact names only — no aliases (spec G4).
source	str		Query column being aggregated. Always required alongside aggregate: (spec G2).
format	str | FormatConfig	✓	D3 format string or format config object for the aggregated value. Optional.
label	str	✓	Column header label override for this row.

ChartDataTablePerSeries

A data_table entry that expands into one row per color: series.

Field	Type	Optional	Description
per_series	str		Query column the row reads from (per-x, per-series value).
by_measure	bool	✓	When True, expand one row reading the named measure field directly (no color: groupby). Required for multi-y charts where each measure is its own y-field rather than a color-encoded series.
label	str	✓	Row label displayed in the strip's label gutter. When None and by_measure=True, the per_series column name is used. Has no effect when by_measure=False (series name is the label).
format	str | FormatConfig	✓	D3 format string or format config object. Optional.

FontStyle

Text appearance. Merged as a unit.

Field	Type	Optional	Description
family	str	✓	Font family name (e.g., 'sans-serif', 'Roboto').
color	str	✓	Text color as a CSS color string.
size	float	✓	Font size in pixels.
weight	str | float	✓	Font weight (e.g., 'bold', 400, 700).
style	enum: "normal", "italic"	✓	Font style (normal or italic).
decoration	enum: "none", "line-through", "underline"	✓	Text decoration (underline, line-through, or none).
case	enum: "none", "sentence", "title", "upper", "lower", "slug", "camel"	✓	Letter-case transform applied at render time. 'title' uses Chicago/Gruber rules and preserves tokens with internal capitals (ARR, iPhone). 'sentence' uppercases only the first character. 'none' (default) emits the string without any letter-case change.
line_height	float	✓	Line height as a unitless multiple of font size. Cascades through Style.font to all text roles that carry a FontStyle slot. Body prose defaults to 1.25; titles override tighter via their font patch in theme YAML.

PaddingStyle

Authored overlay for PaddingStyle. Per-chart padding inset (px). All 4 sides required; theme YAML supplies defaults.

Field	Type	Optional	Description
left	float	✓	Left padding in pixels.
right	float	✓	Right padding in pixels.
top	float	✓	Top padding in pixels.
bottom	float	✓	Bottom padding in pixels.

LegendStyle

Authored overlay for LegendStyle.

Field	Type	Optional	Description
position	str	✓	Legend position (e.g. 'right', 'bottom').
direction	str	✓	Legend layout direction ('vertical' or 'horizontal').
label	LegendLabelStyle	✓	Legend label style.
title	LegendTitleStyle	✓	Legend title style.
visible	bool	✓	Show the legend. None = legend visible; False = explicitly suppressed.
interactive_legend	bool	✓	Emit a dft_legend point-selection param for single-click series toggle.
symbol_limit	int	✓	Maximum number of legend entries to display; maps to VL symbolLimit. None uses Vega-Lite's default (no cap). Set to a positive integer to prevent legend overflow on high-cardinality series.
values	list[str]	✓	Explicit legend entry order/filter; maps to VL legend.values. None lets the renderer infer order from the data.

TooltipStyle

Authored overlay for TooltipStyle. Tooltip box style — all cascade keys for the hover bubble.

Field	Type	Optional	Description
format	str	✓	Default tooltip value format string; theme always provides this.
background	str	✓	Tooltip background color (CSS color string); theme always provides this.
line_height	float	✓	Tooltip line-height multiplier; theme always provides this.
max_width	float	✓	Maximum tooltip width in pixels; theme always provides this.
gap	float	✓	Gap in pixels between label and value columns; theme always provides this.
font	FontStyle	✓	Tooltip font overrides (size etc.); cascade fills missing fields. Unset fields fall back to style.charts.font.
padding	PaddingStyle	✓	Tooltip inner padding (4 sides in pixels); theme always provides this.
label	TooltipSlotStyle	✓	Label-column font overrides (color, weight).
value	TooltipSlotStyle	✓	Value-column font overrides (color, weight).
border	TooltipBorderStyle	✓	Tooltip border style; theme always provides this.
shadow	TooltipShadowStyle	✓	Tooltip drop-shadow config; theme always provides this.

StyleColorConfig

Chart-local style color: gradient scale for the color channel.

Field	Type	Description
scale	ScaleTargetConfig	Continuous color scale applied to the chart's color channel.

AxisStyle

Authored overlay for AxisStyle.

Field	Type	Optional	Description
grid	AxisGridStyle	✓	Grid line style for this axis.
domain	AxisDomainStyle	✓	Domain line style for this axis.
ticks	AxisTicksStyle	✓	Tick mark style for this axis.
label	AxisElementStyle	✓	Axis label style.
title	AxisElementStyle	✓	Axis title style.
position	enum: "left", "right", "top", "bottom", "auto"	✓	Axis position; auto flips y-axis when endpoint labels are present.
categorical_orient	str	✓	Orientation for categorical y-axis (e.g. 'left'); None skips this VL property.
mirror	bool | AxisMirrorStyle	✓	Draw the y-scale on both left and right edges (wide charts). true mirrors the primary axis's label verbatim; an object (format/expr) relabels only the mirrored edge — e.g. a percent-of-total right axis next to an absolute-value left axis — while ticks stay aligned to the single shared scale. Only meaningful on axis_y.
band_position	float	✓	Band position within the step (0–1); None uses Vega-Lite's default.
offset	float	✓	Pixel offset of the axis from its default position; None means no offset.
format	str	✓	Tick value format string; None uses auto-format.
values	list[Any]	✓	Explicit tick values; None uses Vega-Lite's auto tick values.
time_unit	enum: "auto", "year", "yearquarter", "yearmonth", "yearweek", "yearmonthdate", "monthofyear", "dayofweek", "dayofmonth", "dayofyear", "hourofday", "none"	✓	Time-unit bucketing for temporal x-axes; None or 'auto' auto-detects from data.
scale	ScaleStyle	✓	Per-axis scale overrides; None means no override.
type	enum: "auto", "ordinal", "temporal"	✓	Scale type for bucketed-time x-axes; None/'auto' infers from time_unit grain.
fill	enum: "null", "zero", "linear", "step-after", "step-before", "step-center", "curve"	✓	Fill for synthesized missing-bucket rows: null, zero, linear, step-after / step-before / step-center (Looker step), or curve (smoothstep).

ScaleStyle

Authored overlay for ScaleStyle. Scale configuration primitive.

Field	Type	Optional	Description
band_padding_inner	float	✓	Inner padding fraction for band scales; None uses Vega-Lite's default.
band_padding_outer	float	✓	Outer padding fraction for band scales; None uses Vega-Lite's default.
point_padding	float	✓	Padding fraction for point scales; None uses Vega-Lite's default.
rect_band_padding_inner	float	✓	Inner padding fraction for rect band scales; None uses Vega-Lite's default.
round	bool	✓	Round scale outputs to nearest integer; None uses Vega-Lite's default (no rounding).
zero	bool | enum: "auto"	✓	Force scale zero-baseline: True/False pins it; "auto" runs the Dataface smart-zero heuristic; None passes through to Vega-Lite.
clamp	bool	✓	Clamp values to scale domain; None uses Vega-Lite's default (no clamping).
continuous_padding	float	✓	Padding in pixels for continuous scales; None uses Vega-Lite's default.
band	ScaleBandStyle	✓	Band mark size constraints; None uses Vega-Lite's defaults.
quantile_count	int	✓	Number of quantile buckets; None uses Vega-Lite's default.
quantize_count	int	✓	Number of quantize buckets; None uses Vega-Lite's default.
use_unaggregated_domain	bool	✓	Use unaggregated domain for scale extent; None uses Vega-Lite's default.
x_reverse	bool	✓	Reverse the x-axis scale direction; None means no reversal.
type	enum: "linear", "log", "pow", "sqrt", "symlog", "temporal"	✓	Scale type override. 'linear'/'log'/'pow'/'sqrt'/'symlog' pass straight through to Vega-Lite's quantitative scale.type. 'temporal' is a Dataface escape hatch for a cartesian x-axis: it forces a continuous temporal scale instead of the auto-inferred ordinal/nominal bucketed type, which is required before an authored domain of ISO dates can extend the visible range past the data extent. None lets Dataface/Vega-Lite infer from the field type.
domain	list[Any]	✓	Explicit [low, high] scale domain; None lets Vega-Lite auto-determine from data. Must have exactly 2 elements — Dataface only wires a continuous range override through to Vega-Lite, not an explicit category enumeration. When type: temporal is set, both elements must be ISO-8601 date/datetime strings.
nice	bool	✓	Round scale domain to nice values; None uses Vega-Lite's default.
padding	float	✓	Unified scale padding shortcut; dispatches to band, point, or continuous padding per scale type.

DataTableStyle

Authored overlay for DataTableStyle. Attached data_table style. Lives at style.charts.data_table.*.

Field	Type	Optional	Description
font	FontStyle	✓	Data_table font style overrides. Unset fields fall back to style.charts.font.
divider	RuleStyle	✓	Rule at the boundary between the chart plot and the data strip. For position='bottom': rule sits above the strip (below the axis). For position='top': rule sits below the strip rows (above the plot top).
row	DataTableRowStyle	✓	Data_table row padding and rule style.
label	DataTableLabelStyle	✓	Row label (series name) style.
padding_top	float	✓	Padding above the topmost strip row in pixels. For position='bottom': gap between axis labels and the first row. For position='top': space above the topmost row (outer edge of strip).
padding_bottom	float	✓	Padding below the last strip row in pixels. For position='bottom': space below the last row. For position='top': gap between the last row and the plot top edge.
label_max_lines	int	✓	Number of x-axis label lines to reserve in the axis gap (only used for position='bottom'; ignored for position='top'). Typically 1 or 2.
position	enum: "top", "bottom"	✓	Strip placement relative to the chart plot. 'top' places the strip above the plot (no x-axis gap needed); 'bottom' places it below with the x-axis between plot and strip.

EndpointLabelsConfig

Authored overlay for EndpointLabelsConfig. Endpoint label pane config — shared across line, area, and bar.

Field	Type	Optional	Description
visible	bool	✓	Show endpoint labels; theme sets false, authors opt in per chart.
label_offset	float	✓	Spacing in pixels between the chart pane and the label pane.
height	float	✓	Height in pixels of the endpoint-label pane (top_rail layout).

BarChartMarksStyle

Authored overlay for BarChartMarksStyle. Bar-family mark overrides. Only bar and text (endpoint labels) are valid.

Field	Type	Optional	Description
bar	BarMarkStyle	✓	Bar mark overrides for bar charts; inherits from global.
text	TextMarkStyle	✓	Text mark overrides for bar endpoint labels; inherits from global.

LineChartMarksStyle

Authored overlay for LineChartMarksStyle. Line-family mark overrides.

Field	Type	Optional	Description
line	LineMarkStyle	✓	Line mark overrides; inherits from global.
point	PointMarkStyle	✓	Point mark overrides; inherits from global.
text	TextMarkStyle	✓	Text mark overrides; inherits from global.
rule	RuleMarkStyle	✓	Rule mark overrides; None inherits global.

AreaChartMarksStyle

Authored overlay for AreaChartMarksStyle. Area-family mark overrides.

Field	Type	Optional	Description
area	AreaMarkStyle	✓	Area mark overrides; inherits from global.
line	LineMarkStyle	✓	Top-edge line mark overrides; inherits from global.
point	PointMarkStyle	✓	Point mark overrides; inherits from global.
text	TextMarkStyle	✓	Text mark overrides; inherits from global.

ScatterChartMarksStyle

Authored overlay for ScatterChartMarksStyle. Scatter-family mark overrides.

Field	Type	Optional	Description
point	PointMarkStyle	✓	Point mark overrides; inherits from global.
text	TextMarkStyle	✓	Text mark overrides; inherits from global.

HeatmapChartMarksStyle

Authored overlay for HeatmapChartMarksStyle. Heatmap-family mark overrides.

Field	Type	Optional	Description
rect	RectMarkStyle	✓	Rect mark overrides; inherits from global.
text	TextMarkStyle	✓	Text mark overrides; None inherits global.

TotalStyle

Authored overlay for TotalStyle. Donut center total paint: value (the number) and label (the caption).

Field	Type	Optional	Description
value	TotalSlotStyle	✓	Style for the donut center value (the number).
label	TotalSlotStyle	✓	Style for the donut center label (the caption).

PieChartMarksStyle

Authored overlay for PieChartMarksStyle. Pie/donut-family mark overrides.

Field	Type	Optional	Description
slice	SliceMarkStyle	✓	Slice mark overrides; inherits from global.
text	TextMarkStyle	✓	Text mark overrides; None inherits global.

KpiValueStyle

Authored overlay for KpiValueStyle. KPI headline value slot: font and format. Theme populates font.size directly.

Field	Type	Optional	Description
font	FontStyle	✓	KPI value font style. Unset fields fall back to style.charts.kpi.font.
format	str | FormatConfig	✓	Number format for the KPI headline value: D3 format string, preset name, or FormatConfig object.

KpiSlotStyle

Authored overlay for KpiSlotStyle. KPI per-slot style for label, affix, and glyph slots.

Field	Type	Optional	Description
font	FontStyle	✓	Slot font style. Unset fields fall back to style.charts.kpi.font.
character	str	✓	Glyph character to render (e.g. '▲'). None = no glyph.

KpiTonesStyle

Authored overlay for KpiTonesStyle. Semantic tone palette for KPI value/glyph and (eventually) tables.

Field	Type	Optional	Description
positive	str	✓	Color for positive/good tone indicators.
negative	str	✓	Color for negative/bad tone indicators.
warning	str	✓	Color for warning/caution tone indicators.

TableRuleStyle

Authored overlay for TableRuleStyle. Table rule color override block.

Field	Type	Optional	Description
color	str	✓	Table rule color; None uses the theme default.

TableColumnsStyle

Authored overlay for TableColumnsStyle.

Field	Type	Optional	Description
default_width	float	✓	Default column width in pixels.
cell_padding	float	✓	Horizontal padding inside table cells in pixels.
width_similarity_threshold	float	✓	Auto-width columns whose min/max ratio >= this threshold are snapped to a shared width before budget allocation. 1.0 disables clustering; 0.0 forces all auto-columns to equal width.
content_headroom	float	✓	Fractional breathing room added above the raw p95 column demand when pinning compact columns in mixed (compact + text) tables. 0.10 means each compact column is pinned at 10 % above its measured demand; the extra width is funded by the text-column budget. Has no effect on all-compact tables (proportional scaling already fills the budget). 0.0 disables headroom.

TableHeaderStyle

Authored overlay for TableHeaderStyle.

Field	Type	Optional	Description
visible	bool	✓	Show the header row (column labels + rule). Set to False on series-keyed tables where column meanings are obvious from context (e.g. donut-attached tables: swatch / share / name / value). Theme YAML supplies the UX default (true) via _base.yaml.
height	float	✓	Header row height in pixels.
font	FontStyle	✓	Header font style overrides. Unset fields fall back to style.charts.table.font.
font_compact	FontStyle	✓	Compact-tier font overrides applied when body size ≤11px; None means no compact override.
background	str	✓	Header background color; None means no fill (rule alone separates header from body).
overflow	str	✓	Header text overflow mode (clip, truncate, wrap).
rule	RuleStyle	✓	Header bottom rule style.

TableRowStyle

Authored overlay for TableRowStyle.

Field	Type	Optional	Description
height	float	✓	Body row height in pixels.
stripe	TableRowStripeStyle	✓	Alternating row stripe style; None means no stripe.
rule	RuleStyle	✓	Row bottom rule style.
role	str	✓	Default row role assignment; None means plain body row.
roles	TableRowRolesStyle	✓	Per-role style overrides for summary and total rows.

TableRowNumbersStyle

Authored overlay for TableRowNumbersStyle. Leading row-number column (style.table.row_numbers).

Field	Type	Optional	Description
visible	bool	✓	Show a leading row-number column; false by default.
header	str	✓	Header label for the row-number column.
align	enum: "left", "right"	✓	Text alignment for the row-number column.

TableTitleStyle

Authored overlay for TableTitleStyle.

Field	Type	Optional	Description
height	float	✓	Table title row height in pixels.
font	FontStyle	✓	Table title font style overrides. Unset fields fall back to style.charts.table.font.

PaginationConfig

Table pagination configuration.

Field	Type	Optional	Description
enabled	bool	✓	Enable client-side pagination for table charts.
page_rows	int	✓	Rows per page. When enabled and None, the renderer auto-fits page size to the cell — set explicitly to pin the page size.

TableColumnDefaultsConfig

Table-level defaults applied to every column unless overridden per-column.

Field	Type	Optional	Description
label	str	✓	Override column header label text.
width	int | str	✓	Override column width in pixels (integer) or a CSS width string.
align	enum: "left", "center", "right"	✓	Override cell text alignment (left, center, or right).
format	str | FormatConfig	✓	Override cell value format (D3 format string or format config object).
background	str	✓	Override cell background color (CSS color string).
font	FontStyle	✓	Override cell font style (size, weight, color, family).

TableColumnConfig

Configuration for a single table column.

Field	Type	Optional	Description
label	str	✓	Display header label (defaults to column name).
format	str | FormatConfig	✓	Number format (D3 string, preset name, or FormatConfig).
spark	enum: "line", "area", "bar", "bar-normalize", "column", "columns"	✓	Inline spark chart config or spark type name.
swatch	bool	✓	When True, render this column's cells as small rounded color squares instead of text. Cell value must be a CSS color string (e.g. '#3164a3'). Useful for series-keyed tables — e.g. a 'Series' column where each row is identified by its color in the parent chart's palette.
width	int | str	✓	Column width (integer pixels or CSS string like '10%').
max_width	int | str	✓	Maximum column width for auto-sized text columns (integer pixels or CSS string like '30%'). Cannot be set together with width:.
align	enum: "left", "center", "right"	✓	Text alignment in cells (left, center, right).
header_overflow	enum: "clip", "truncate", "wrap-two", "wrap"	✓	Header text overflow mode (clip, truncate, wrap-two, wrap).
header_link	str	✓	URL template for the column header link.
link	str	✓	URL template for cell values (Jinja template with row fields available).
background	str	✓	Cell background color (CSS color string).
font	FontStyle	✓	Cell font style overrides.
scale	ColumnScaleConfig	✓	Continuous color mapping configuration for this column.
glyph	str	✓	Glyph character prepended to cell values.
glyph_color	str	✓	Color for the glyph. Requires glyph to be set.

PaginatorStyle

Authored overlay for PaginatorStyle. Visual style for the paginator control (chevrons + page numbers).

Field	Type	Optional	Description
color_active	str	✓	Current page and live chevron color (theme body ink).
color_inactive	str	✓	Other pages and ellipsis color (theme secondary text).
color_disabled	str	✓	Chevron color when at first/last page (signals disabled by tone).
font	FontStyle	✓	Paginator font overrides (size, family).
weight_active	int	✓	Font weight for the current (selected) page number.
weight_inactive	int	✓	Font weight for other pages and ellipsis.
weight_chevron	int	✓	Font weight for the prev/next chevrons (live and disabled). Usually heavier than weight_active so the chevrons read as interactive affordances against the lighter page numbers.
item_width	float	✓	Per-item slot width in pixels (drives layout step).

TableEdgeStyle

Authored overlay for TableEdgeStyle. more_rows or empty_state edge-case UI.

Field	Type	Optional	Description
font	FontStyle	✓	Edge-case UI (more_rows / empty_state) font style overrides. Unset fields fall back to style.charts.table.font.

SparkStyle

Authored overlay for SparkStyle. Inline sparkline defaults (inside table cells).

Field	Type	Optional	Description
color	str	✓	Sparkline line/point color; None seeds from style.charts.single_series_palette[0].
padding	SpacingValues	✓	Cell padding around the sparkline in pixels.
empty	SparkEmptyStyle	✓	Style for empty/no-data sparklines.
single_value	SparkSingleValueStyle	✓	Style for single-data-point sparklines.
columns	SparkColumnsStyle	✓	Style for column-type sparklines.
column	SparkColumnStyle	✓	Style for the single vertical column spark mark.
bar	SparkBarCellStyle	✓	Style for bar/bar-normalize sparklines.
area	SparkAreaStyle	✓	Style for area sparklines.

SubtitleStyle

Authored overlay for SubtitleStyle. Subtitle font style for chart subtitles (Table, SparkBar).

Field	Type	Optional	Description
font	FontStyle	✓	Subtitle font style; theme populates font.size directly.

ProjectionStyle

Authored overlay for ProjectionStyle. Vega-Lite map projection configuration for geo chart families.

Field	Type	Optional	Description
type	str	✓	Vega-Lite projection type (e.g. 'mercator', 'albersUsa', 'equalEarth').

BasemapStyle

Authored overlay for BasemapStyle. Background map layer for geo charts (especially point maps).

Field	Type	Optional	Description
source	str	✓	Background topo source identifier; None means no base layer.

PointMapChartMarksStyle

Authored overlay for PointMapChartMarksStyle. Point map-family mark overrides.

Field	Type	Optional	Description
point	PointMarkStyle	✓	Point mark overrides; inherits from global.

GeoshapeChartMarksStyle

Authored overlay for GeoshapeChartMarksStyle. Geoshape-family mark overrides.

Field	Type	Optional	Description
geoshape	GeoshapeMarkStyle	✓	Geoshape mark overrides; inherits from global.

LayerAxisYStyle

Per-layer y-axis settings on a layered chart.

Field	Type	Optional	Description
position	enum: "left", "right"	✓	Y-axis side for this layer (left or right).
title	str	✓	Y-axis title override for this layer.

LayeredMarksStyle

Per-mark-type style overrides for layered charts.

Field	Type	Optional	Description
bar	BarMarkStyle	✓	Bar mark overrides for bar layers.
line	LineMarkStyle	✓	Line mark overrides for line layers.
area	AreaMarkStyle	✓	Area mark overrides for area layers.
point	PointMarkStyle	✓	Point/dot mark overrides shared across line and area layers.

CalloutElementStyle

Authored overlay for CalloutElementStyle. Font + y_offset for a callout title or message.

Field	Type	Optional	Description
font	FontStyle	✓	Element font style overrides. Unset fields fall back to style.charts.font.
y_offset	float	✓	Vertical offset from the element's anchor in pixels.

SparkBarBarStyle

Authored overlay for SparkBarBarStyle. Bar geometry sub-block for SparkBarChartStyle.

Field	Type	Optional	Description
height	float	✓	Height of each bar in pixels.
padding	float	✓	Vertical padding between bars in pixels.
color	str	✓	Bar fill color; None seeds from style.charts.single_series_palette[0].
background	str	✓	Bar track background color. Falls back to style.muted.

SparkBarChartLabelStyle

Authored overlay for SparkBarChartLabelStyle. Category-label sub-block for SparkBarChartStyle.

Field	Type	Optional	Description
visible	bool	✓	Show series label text next to bars.
width	float	✓	Reserved width for bar label text in pixels.

SparkBarCountStyle

Authored overlay for SparkBarCountStyle. Count-value sub-block for SparkBarChartStyle.

Field	Type	Optional	Description
visible	bool	✓	Show count/value text next to bars.
width	float	✓	Reserved width for bar count text in pixels.

ForeachQuery

Inline data source for compile-time foreach loops.

Field	Type	Optional	Description
data	list[dict[str, Any]]	✓	Inline row data for compile-time iteration.
static_data	list[dict[str, Any]]	✓	Alias for data; inline row data for compile-time iteration.

TitleWidthOffsetsStyle

Authored overlay for TitleWidthOffsetsStyle. Additive level offsets applied to a face/chart title's heading level, by card pixel width.

Field	Type	Optional	Description
tiny	int	✓	Level offset for the tiny tier (cards narrower than ~360px).
narrow	int	✓	Level offset for the narrow tier (cards ~360–559px).
medium	int	✓	Level offset for the medium tier (cards ~560–1099px).
wide	int	✓	Level offset for the wide tier (cards ~1100px and up).

TitlePositionStyle

Authored overlay for TitlePositionStyle. Vega-Lite title positioning pass-throughs grouped as a sub-object.

Field	Type	Optional	Description
anchor	str	✓	Title anchor position; theme always sets this.
angle	float	✓	Title rotation angle in degrees; None lets Vega-Lite choose.
offset	float	✓	Title offset from its anchor in pixels; None uses Vega-Lite's default.
baseline	str	✓	Title text baseline alignment; None uses Vega-Lite's default.

TitleSubtitleStyle

Authored overlay for TitleSubtitleStyle. VL subtitle font pass-through, grouped for consistency with TitleStyle.font.

Field	Type	Optional	Description
font	FontStyle	✓	Subtitle font style overrides (color, family, size, weight). Unset fields fall back to style.font.

BlockMarginStyle

Authored overlay for BlockMarginStyle. Top and bottom margin for a prose block role, in line-height units.

Field	Type	Optional	Description
margin_top	float	✓	Space above the block, in line-height units (lh × font_size × value).
margin_bottom	float	✓	Space below the block, in line-height units (lh × font_size × value).

TextColumnStyle

Authored overlay for TextColumnStyle. Multi-column layout for face body text (CSS column-count/gap/rule/max_chars).

Field	Type	Optional	Description
number	int	✓	Fixed column count. None = single column.
gap	float	✓	Gap between columns in pixels. None = use layout gap token.
rule	str	✓	CSS column-rule shorthand, e.g. '1px solid #e5e7eb'. None = no rule.
max_chars	int	✓	Target column width as a character count. The pixel width is derived at render time via fonttools OS/2.xAvgCharWidth × max_chars; column count auto-derives as ceil(available / col_width_px).

TextCodeStyle

Authored overlay for TextCodeStyle. Inline and fenced code spans in markdown prose. Box group; mono font by default.

Field	Type	Optional	Description
font	FontStyle	✓	Box text font overrides — full FontStyle (family, color, size, weight, style, decoration, case).
background	str	✓	Box background fill.
border	BorderStyle	✓	Box border (width, color, radius).

TextBlockquoteStyle

Authored overlay for TextBlockquoteStyle. Blockquote prose. Box group; border is the left rule.

Field	Type	Optional	Description
font	FontStyle	✓	Box text font overrides — full FontStyle (family, color, size, weight, style, decoration, case).
background	str	✓	Box background fill.
border	BorderStyle	✓	Box border (width, color, radius).

PlaceholderOverlay

Authored overlay for PlaceholderOverlay.

Field	Type	Optional	Description
text	str	✓	Placeholder overlay text shown on empty charts.
background	str	✓	Overlay background color.
font	FontStyle	✓	Overlay font style overrides. Unset fields fall back to style.font.

ViewStyle

Authored overlay for ViewStyle.

Field	Type	Optional	Description
stroke	str	✓	Plot area border stroke color; None means no border.
continuous_width	float	✓	Default plot width for continuous (quantitative) scales in pixels.
continuous_height	float	✓	Default plot height for continuous (quantitative) scales in pixels.
discrete_width	float	✓	Default plot width for discrete (ordinal/nominal) scales in pixels; None means auto.
discrete_height	float	✓	Default plot height for discrete (ordinal/nominal) scales in pixels; None means auto.

AutosizeStyle

Authored overlay for AutosizeStyle.

Field	Type	Optional	Description
type	str	✓	Vega-Lite autosize type (e.g. 'fit', 'fit-x', 'pad').
contains	str	✓	What the autosize dimensions include ('content' or 'padding').
resize	bool	✓	Recompute autosize on each render cycle.

GlobalMarksStyle

Authored overlay for GlobalMarksStyle. Global mark defaults: one MarkStyle per VL mark type.

Field	Type	Optional	Description
bar	BarMarkStyle	✓	Global bar mark defaults.
line	LineMarkStyle	✓	Global line mark defaults.
area	AreaMarkStyle	✓	Global area mark defaults.
point	PointMarkStyle	✓	Global point mark defaults.
slice	SliceMarkStyle	✓	Global slice (arc/pie) mark defaults.
text	TextMarkStyle	✓	Global text mark defaults.
rule	RuleMarkStyle	✓	Global rule mark defaults.
rect	RectMarkStyle	✓	Global rect mark defaults.
circle	CircleMarkStyle	✓	Global circle mark defaults.
square	SquareMarkStyle	✓	Global square mark defaults.
tick	TickMarkStyle	✓	Global tick mark defaults.
trail	TrailMarkStyle	✓	Global trail mark defaults.
geoshape	GeoshapeMarkStyle	✓	Global geoshape mark defaults.

HistogramChartStyle

Authored overlay for HistogramChartStyle. Histogram chart style.

Field	Type	Optional	Description
font	FontStyle	✓	Chart-level font overrides.
aspect_ratio	float	✓	Chart aspect ratio (width/height). Falls back to style.charts.aspect_ratio.
min_height	float	✓	Minimum chart height in pixels. Falls back to style.charts.min_height.
max_height	float	✓	Maximum chart height in pixels. Falls back to style.charts.max_height.
padding	PaddingStyle	✓	Per-chart-type padding override; 4 sides in pixels. Unset fields fall back to style.charts.padding.
border	BorderStyle	✓	Chart card border style.
animation_duration	float	✓	Vega-Lite animation duration in milliseconds. Falls back to style.charts.animation_duration.
palette	list[str] | str	✓	Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to style.charts.palette.
single_series_palette	list[str] | str	✓	Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to style.charts.single_series_palette.
legend	LegendStyle	✓	Chart legend style.
tooltip	TooltipStyle	✓	Per-chart-type tooltip style override; None uses the universal style.charts.tooltip.
background	str	✓	Chart-local background color override; None inherits from theme.
color	str | StyleColorConfig	✓	Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette.
title	TitleStyle	✓	Chart-level title style override; None inherits the theme title style.
axis	AxisStyle	✓	Override applied to both x and y axes; None inherits the global axis at render.
axis_x	AxisStyle	✓	Per-chart-type x-axis style overrides; None inherits the global axis_x at render.
axis_y	AxisStyle	✓	Per-chart-type y-axis style overrides; None inherits the global axis_y at render.
axis_quantitative	AxisStyle	✓	Per-chart-type quantitative-axis overrides; None inherits the global axis_quantitative at render.
axis_band	AxisStyle	✓	Per-chart-type categorical (band) axis overrides; None inherits the global band axis at render.
number_format	str	✓	Default number format for axes and tooltips (D3 format string); None inherits from theme.
time_format	str	✓	Default time format for temporal axes (D3 time format string); None inherits from theme.
scale	ScaleStyle	✓	Chart-type encoding scale overrides applied to both x and y; None means no override.
data_table	DataTableStyle	✓	Per-chart-type data_table style override. Unset fields fall back to style.charts.data_table.
bin_maxbins	int	✓	Maximum number of bins for auto-binning.
marks	HistogramChartMarksStyle	✓	Histogram-family mark overrides. Unset fields fall back to style.charts.marks.

SeriesLabelStyle

Authored overlay for SeriesLabelStyle. Series-label primitive — typography for any text mark that names a

Field	Type	Optional	Description
font	FontStyle	✓	Series label font style overrides; cascade fills missing fields from charts.font. Unset fields fall back to style.charts.font.

LayoutGapStyle

Authored overlay for LayoutGapStyle.

Field	Type	Optional	Description
gap	float	✓	Gap between layout items in pixels.

GridLayoutStyle

Authored overlay for GridLayoutStyle.

Field	Type	Optional	Description
columns	int	✓	Number of columns in the grid layout.
gap	float	✓	Gap between grid cells in pixels.

TabsStyle

Authored overlay for TabsStyle.

Field	Type	Optional	Description
bar_height	float	✓	Tab bar height in pixels.
border	BorderStyle	✓	Tab bar border style.
font	FontStyle	✓	Tab label font style overrides. Unset fields fall back to style.font.
active_weight	str	✓	Font weight for the active tab label.
inactive_weight	str	✓	Font weight for inactive tab labels.
title_baseline_offset	float	✓	Vertical offset to align SVG tab label baseline in pixels.

DetailsStyle

Authored overlay for DetailsStyle.

Field	Type	Optional	Description
summary_height	float	✓	Height of the details summary (collapsed) row in pixels.
border	BorderStyle	✓	Details element border style.
font	FontStyle	✓	Details summary font style overrides. Unset fields fall back to style.font.
arrow	DetailsArrowStyle	✓	Expand/collapse arrow glyph layout and font style.
label_x	float	✓	X position of the details summary label text in pixels.
text_baseline_offset	float	✓	Vertical offset to align SVG details text baseline in pixels.
content_y_offset	float	✓	Y offset of the expanded details content area in pixels.

VariablesLabelStyle

Authored overlay for VariablesLabelStyle. Per-label font substyle for variable controls. Cascades from variables.font.

Field	Type	Optional	Description
font	FontStyle	✓	Variable label font style overrides. Unset fields fall back to style.variables.font.

VariablesValueStyle

Authored overlay for VariablesValueStyle. Per-value font substyle for variable controls. Cascades from variables.font.

Field	Type	Optional	Description
font	FontStyle	✓	Variable value font style overrides. Unset fields fall back to style.variables.font.
numeric_variant	enum: "normal", "tabular-nums"	✓	OpenType numeric feature for value displays ('normal' or 'tabular-nums').

VariablesPlaceholderStyle

Authored overlay for VariablesPlaceholderStyle. Per-placeholder font substyle for variable controls.

Field	Type	Optional	Description
font	FontStyle	✓	Variable placeholder-text font style overrides. Unset fields fall back to style.variables.font.

InputStyle

Authored overlay for InputStyle.

Field	Type	Optional	Description
height	float	✓	Input control height in pixels.
border	BorderStyle	✓	Input border style.
focus_color	str	✓	Input focus ring color. Falls back to style.accent.
background	str	✓	Input background color.
padding	SpacingValues	✓	Input inner padding in pixels.
widths	InputWidths	✓	Per-input-type default widths.
range	RangeDefaults	✓	Range input default min/max/step values.

FooterRule

Authored overlay for FooterRule. Hairline rule above the footer attribution text. None = no rule.

Field	Type	Optional	Description
color	str	✓	Rule stroke color.
stroke_width	float	✓	Rule stroke width in pixels.

LegendLabelStyle

Authored overlay for LegendLabelStyle.

Field	Type	Optional	Description
font	FontStyle	✓	Legend element font style overrides. Unset fields fall back to style.charts.font.
padding	float	✓	Padding between legend symbol and element text in pixels.
max_width	float	✓	Maximum label width in pixels; maps to VL labelLimit. None uses Vega-Lite's default.

LegendTitleStyle

Authored overlay for LegendTitleStyle.

Field	Type	Optional	Description
font	FontStyle	✓	Legend element font style overrides. Unset fields fall back to style.charts.font.
padding	float	✓	Padding between legend symbol and element text in pixels.
visible	bool	✓	Show the legend title; None = shown, False = suppressed (VL legend.title: null).

TooltipSlotStyle

Authored overlay for TooltipSlotStyle. Typography for a single tooltip slot (label or value).

Field	Type	Optional	Description
font	FontStyle	✓	Font overrides for this tooltip slot (color, weight). Unset fields fall back to style.charts.font.

TooltipBorderStyle

Authored overlay for TooltipBorderStyle. Tooltip box border — all fields required; theme YAML supplies defaults.

Field	Type	Optional	Description
color	str	✓	Border color as a CSS color string.
width	float	✓	Border width in pixels.
radius	float	✓	Border corner radius in pixels.

TooltipShadowStyle

Authored overlay for TooltipShadowStyle. Tooltip drop-shadow toggle. JS applies the shadow expression when visible=true.

Field	Type	Optional	Description
visible	bool	✓	Show a drop-shadow on the tooltip box; theme always provides this.

ScaleTargetConfig

Scale configuration for a single style target (background or color).

Field	Type	Optional	Description
palette	list[str] | list[float] | str		Color palette: CSS color list for categorical, float list for relative stops, or a named Vega scheme.
domain	enum: "data"	✓	Scale domain source ('data' uses the data extent; None uses explicit min/max).
min	float | int	✓	Minimum scale domain value (overrides data minimum).
max	float | int	✓	Maximum scale domain value (overrides data maximum).
null_color	str	✓	Color assigned to null values.
hinge	float | enum: "auto"	✓	Diverging scale midpoint value, or 'auto' to use the data midpoint.
arm_mode	enum: "asymmetric", "symmetric"	✓	How diverging scale arms are stretched: 'asymmetric' (proportional) or 'symmetric' (equal arms).

AxisGridStyle

Authored overlay for AxisGridStyle.

Field	Type	Optional	Description
visible	bool	✓	Show grid lines; None inherits from parent axis.
opacity	float	✓	Grid line opacity; None uses Vega-Lite's default.
width	float	✓	Grid line width in pixels; None uses Vega-Lite's default.
color	str	✓	Grid line color; None uses Vega-Lite's default.
dash	list[float]	✓	Dash pattern for grid lines; None renders a solid line.
zero	AxisGridZeroStyle	✓	Zero-baseline gridline style; None inherits from parent axis.

AxisDomainStyle

Authored overlay for AxisDomainStyle.

Field	Type	Optional	Description
visible	bool	✓	Show the axis domain line; None inherits from parent axis.
width	float	✓	Domain line width in pixels; None uses Vega-Lite's default.
color	str	✓	Domain line color; None uses Vega-Lite's default.

AxisTicksStyle

Authored overlay for AxisTicksStyle.

Field	Type	Optional	Description
visible	bool	✓	Show axis ticks; None inherits from parent axis.
color	str	✓	Tick color; None uses Vega-Lite's default.
size	float	✓	Tick length in pixels; None uses Vega-Lite's default.
width	float	✓	Tick stroke width in pixels; None uses Vega-Lite's default.
count	int	✓	Target number of axis ticks. On a quantitative axis the renderer computes explicit tickValues so VL emits exactly this many ticks — VL's tickCount is advisory and frequently ignored there. On a temporal axis_x, count is passed through as VL's axis.tickCount, which VL's time-scale tick logic honours as a target.

AxisElementStyle

Authored overlay for AxisElementStyle. Axis label or title: font + padding + VL-passthrough.

Field	Type	Optional	Description
font	FontStyle	✓	Axis element font style overrides. Unset fields fall back to style.charts.font.
padding	float	✓	Padding between axis labels and ticks in pixels; None inherits from parent axis.
max_width	float	✓	Maximum label width in pixels; None uses Vega-Lite's default (180px).
angle	float	✓	Label rotation angle in degrees; None uses Vega-Lite's default.
align	str	✓	Horizontal text alignment of labels; None uses Vega-Lite's default.
baseline	str	✓	Vertical text baseline of labels; None uses Vega-Lite's default.
overlap	enum: "smart", "parity", "greedy", "allow"	✓	Label overlap reduction strategy; None uses Vega-Lite's per-scale default.
separation	float	✓	Minimum pixel separation between labels; None uses Vega-Lite's default (0px).
visible	bool	✓	Show axis labels; None uses Vega-Lite's default (labels shown).
time_unit	enum: "auto", "year", "yearquarter", "yearmonth", "yearweek", "yearmonthdate", "monthofyear", "dayofweek", "dayofmonth", "dayofyear", "hourofday", "none"	✓	Label cadence for temporal axes; None inherits from the parent axis time_unit.
expr	str	✓	Custom Vega expression for label text; None uses smart temporal defaults when applicable.
bound	bool | float	✓	Hide labels that overflow the axis range; None uses Vega-Lite's default.
flush	bool | float	✓	Align first/last label flush with the scale range; None uses Vega-Lite's default.
offset	float	✓	Pixel offset of the label from its tick anchor; None uses Vega-Lite's default.
line_height	float	✓	Line height for multi-line labels in pixels; None uses Vega-Lite's default.
anchor	enum: "start", "middle", "end"	✓	Label anchor position; None uses Vega-Lite's default.
tilt_increments	list[float]	✓	Descending tilt angles for smart label overlap on discrete x-axes; None disables the picker.
values	list[Any]	✓	Dates to keep label text on, chosen from among the axis's ticks (whatever axis_x.values or the auto-fill cadence already produced) — this filters which ticks show text, it does not add or remove ticks. Every tick not in this list keeps its position and gridline but has its label blanked. Set axis_x.values separately to change tick/grid density itself. Temporal x-axes only; None labels every tick as usual.

AxisMirrorStyle

Per-edge label override for the mirrored axis_y.mirror ghost axis.

Field	Type	Optional	Description
format	str	✓	Tick value format string for the mirrored edge; None reuses the primary axis's format.
expr	str	✓	Custom Vega expression for the mirrored edge's label text; None reuses the primary axis's label expression.

ScaleBandStyle

Authored overlay for ScaleBandStyle. Band mark size constraints (min/max pixel width for band-scale marks).

Field	Type	Optional	Description
min_size	float	✓	Minimum band mark width in pixels; None uses Vega-Lite's default.
max_size	float	✓	Maximum band mark width in pixels; None uses Vega-Lite's default.

RuleStyle

Authored overlay for RuleStyle. Shared rule-line primitive: width, color, continuous mode.

Field	Type	Optional	Description
width	float	✓	Rule line width in pixels.
color	str	✓	Rule color; None inherits from theme.
continuous	bool	✓	Draw a continuous full-width rule (true) or only under columns (false).

DataTableRowStyle

Authored overlay for DataTableRowStyle.

Field	Type	Optional	Description
padding	DataTableRowPaddingStyle	✓	Row padding style.
rule	RuleStyle	✓	Row bottom rule style.

DataTableLabelStyle

Authored overlay for DataTableLabelStyle. Row label styling.

Field	Type	Optional	Description
font	FontStyle	✓	Row label font style overrides. Unset fields fall back to style.charts.data_table.font.

BarMarkStyle

Authored overlay for BarMarkStyle. Bar mark geometry and stroke. Chart-level bar fields live on BarChartStyle.

Field	Type	Optional	Description
border	BorderStyle	✓	Bar border style (color/width also serve as the bar stroke).
padding	float	✓	Padding around bar marks in pixels.
size	float	✓	Bar width in pixels (fixed-width mode).
band_width	float	✓	Bar width as a fraction of the band step (0–1).
labels	BarLabelsStyle	✓	Value label style for bar marks.

TextMarkStyle

Authored overlay for TextMarkStyle.

Field	Type	Optional	Description
font	FontStyle	✓	Text mark font style overrides. Unset fields fall back to style.charts.font.
align	str	✓	Horizontal text alignment for text marks.

LineMarkStyle

Authored overlay for LineMarkStyle. Line mark stroke, interpolation, and halo. Point mark lives on PointMarkStyle.

Field	Type	Optional	Description
stroke	StrokeStyle	✓	Line stroke style.
curve	str	✓	Line interpolation curve (e.g. 'linear', 'monotone', 'step-band'). 'step-band' draws a full-band-width plateau per categorical x-value; it requires a band (nominal/ordinal) x-scale.
connect	bool	✓	For curve='step-band', whether adjacent band plateaus are joined by vertical jumps (True/None) or left as disconnected segments (False). No-op for other curves.
halo_multiplier	float	✓	Halo stroke width multiplier relative to stroke.width; 0 disables the halo.
labels	PointLabelsStyle	✓	Value label style for line marks.

PointMarkStyle

Authored overlay for PointMarkStyle. Point mark style (data-point markers on scatter/point/line/area charts).

Field	Type	Optional	Description
size	float	✓	Point size in square pixels; 0 disables points on line charts.
color	str	✓	Point color; None inherits the series color.
shape	str	✓	Point shape (e.g. 'circle', 'square'); None uses VL default.
opacity	float	✓	Point opacity 0–1; None uses VL default.
filled	bool	✓	Whether points are filled; None uses VL default.
fill	str	✓	Point interior fill color; only applied when filled=false.
stroke_width	float	✓	Stroke width in pixels for hollow point rings; None uses VL default.
labels	PointLabelsStyle	✓	Value label style for point marks. On line charts, setting marks.point.labels is an alias for marks.line.labels.

RuleMarkStyle

Authored overlay for RuleMarkStyle. Rule (reference line) mark opacity and stroke.

Field	Type	Optional	Description
opacity	float	✓	Mark opacity (0–1); None means not overridden at this level.
stroke	FontColorStrokeStyle	✓	Mark stroke style.

AreaMarkStyle

Authored overlay for AreaMarkStyle. Area mark fill opacity, stroke, and halo.

Field	Type	Optional	Description
opacity	float	✓	Area fill opacity (0–1).
curve	str	✓	Area interpolation curve (e.g. 'linear', 'monotone', 'step-band'). 'step-band' draws a full-band-width plateau per categorical x-value; it requires a band (nominal/ordinal) x-scale.
stroke	StrokeStyle	✓	Area top-edge stroke style.
halo_multiplier	float	✓	Halo stroke width multiplier relative to stroke.width; 0 disables the halo.
stacked	AreaStackedMarkStyle	✓	Recipe override applied when the chart's stack mode is non-false: solid fill + full-perimeter background-color stroke.

RectMarkStyle

Authored overlay for RectMarkStyle. Rect mark opacity and stroke.

Field	Type	Optional	Description
opacity	float	✓	Mark opacity (0–1); None means not overridden at this level.
stroke	StrokeStyle	✓	Mark stroke style; None means not overridden at this level.

TotalSlotStyle

Authored overlay for TotalSlotStyle. Theme slot for one text element of the donut center total.

Field	Type	Optional	Description
font	FontStyle	✓	Donut center total element font style overrides. Unset fields fall back to style.charts.font.

SliceMarkStyle

Authored overlay for SliceMarkStyle. Pie/donut slice mark — mark-level paint and layout only.

Field	Type	Optional	Description
opacity	float	✓	Arc slice opacity (0–1); None means not overridden at this level.
gap	float	✓	Angular gap between slices in radians.
corner_radius	float	✓	Corner radius of arc slices in pixels.
stroke	StrokeStyle	✓	Arc slice stroke style.
labels	SliceLabelsStyle	✓	Per-slice label style.

TableRowStripeStyle

Authored overlay for TableRowStripeStyle. Alternating row stripe style.

Field	Type	Optional	Description
color	str	✓	Alternating stripe background color; None means no alternating row fill.

TableRowRolesStyle

Authored overlay for TableRowRolesStyle.

Field	Type	Optional	Description
summary	TableRowRoleStyle	✓	Style for summary role rows.
total	TableRowRoleStyle	✓	Style for total role rows.

SparkConfig

Configuration for spark charts (inline sparklines) in table columns.

Field	Type	Optional	Description
type	enum: "line", "area", "bar", "bar-normalize", "column", "columns"	✓	Spark chart type (line, area, bar, bar-normalize, column, columns).
color	str	✓	Color for the spark mark.
height	int	✓	Spark chart height in pixels.
width	int	✓	Spark chart width in pixels.
last_visible	bool	✓	Highlight the last data point (line/area spark charts).
min_max_visible	bool	✓	Annotate the min and max data points (line/area spark charts).
fill_opacity	float	✓	Fill opacity for area spark charts (0–1).
max	float	✓	Maximum value for bar-normalize range scaling.
thresholds	dict[int | float, str]	✓	Color thresholds for bar / bar-normalize: {value: CSS color string}.
background	str	✓	Background track color for bar-normalize chart.
border_radius	float	✓	Border radius for bar-normalize track in pixels.
value_visible	bool	✓	Show numeric value label alongside the bar.
value_suffix	str	✓	Suffix appended to the displayed value label (e.g., '%').

ColumnScaleConfig

Scale-based continuous color mapping for a table column.

Field	Type	Optional	Description
background	ScaleTargetConfig	✓	Continuous background color mapping for this column.
color	ScaleTargetConfig	✓	Continuous text color mapping for this column.

SparkEmptyStyle

Authored overlay for SparkEmptyStyle.

Field	Type	Optional	Description
inset_x	float	✓	Horizontal inset for the empty sparkline placeholder in pixels.
stroke	StrokeStyle	✓	Empty-state placeholder stroke style.

SparkSingleValueStyle

Authored overlay for SparkSingleValueStyle.

Field	Type	Optional	Description
inset_x	float	✓	Horizontal inset for the single-value sparkline in pixels.
marker_radius	float	✓	Radius of the single-value marker circle in pixels.

SparkColumnsStyle

Authored overlay for SparkColumnsStyle. Inline spark.type: columns (multi-value vertical bars) defaults.

Field	Type	Optional	Description
gap	float	✓	Gap between column bars in pixels.
padding	float	✓	Horizontal outer padding of the columns sparkline in pixels.
min_bar_height	float	✓	Minimum rendered bar height in pixels.
border	BorderStyle	✓	Column bar border style.

SparkColumnStyle

Authored overlay for SparkColumnStyle. Inline spark.type: column (single vertical bar) defaults.

Field	Type	Optional	Description
width	float	✓	Spark column default width in pixels.
height	float	✓	Spark column default height in pixels.

SparkBarCellStyle

Authored overlay for SparkBarCellStyle. Inline spark.type: bar and bar-normalize (single horizontal bar) defaults.

Field	Type	Optional	Description
background	str	✓	Track background color. Falls back to style.muted.
color	str	✓	Bar fill color; None seeds from style.charts.single_series_palette[0].
default_max	float	✓	Default maximum value for bar scale when no explicit max is authored.
border	BorderStyle	✓	Spark bar border style.
font	FontStyle	✓	Spark bar cell font style overrides. Unset fields fall back to style.charts.font.
label	SparkBarLabelStyle	✓	Spark bar inline label style.

SparkAreaStyle

Authored overlay for SparkAreaStyle.

Field	Type	Optional	Description
fill_opacity	float	✓	Spark area fill opacity (0–1).

GeoshapeMarkStyle

Authored overlay for GeoshapeMarkStyle. Geoshape (choropleth) mark fill and boundary stroke.

Field	Type	Optional	Description
fill	str	✓	Neutral geoshape fill color.
stroke	StrokeStyle	✓	Geoshape boundary stroke style.

CircleMarkStyle

Authored overlay for CircleMarkStyle. Circle mark opacity and stroke.

Field	Type	Optional	Description
opacity	float	✓	Mark opacity (0–1); None means not overridden at this level.
stroke	StrokeStyle	✓	Mark stroke style; None means not overridden at this level.

SquareMarkStyle

Authored overlay for SquareMarkStyle. Square mark opacity and stroke.

Field	Type	Optional	Description
opacity	float	✓	Mark opacity (0–1); None means not overridden at this level.
stroke	StrokeStyle	✓	Mark stroke style; None means not overridden at this level.

TickMarkStyle

Authored overlay for TickMarkStyle. Tick mark opacity and stroke.

Field	Type	Optional	Description
opacity	float	✓	Mark opacity (0–1); None means not overridden at this level.
stroke	FontColorStrokeStyle	✓	Mark stroke style.

TrailMarkStyle

Authored overlay for TrailMarkStyle. Trail mark opacity and stroke.

Field	Type	Optional	Description
opacity	float	✓	Mark opacity (0–1); None means not overridden at this level.
stroke	StrokeStyle	✓	Mark stroke style; None means not overridden at this level.

HistogramChartMarksStyle

Authored overlay for HistogramChartMarksStyle. Histogram-family mark overrides.

Field	Type	Optional	Description
bar	BarMarkStyle	✓	Bar mark overrides; inherits from global.
rule	RuleMarkStyle	✓	Rule mark overrides; None inherits global.

DetailsArrowStyle

Authored overlay for DetailsArrowStyle. Layout and font style for the expand/collapse arrow chevron.

Field	Type	Optional	Description
x	float	✓	X position of the arrow in pixels.
font	DetailsArrowFontStyle	✓	Arrow glyph font style.

InputWidths

Authored overlay for InputWidths.

Field	Type	Optional	Description
text	float	✓	Default width for text inputs in pixels.
number	float	✓	Default width for number inputs in pixels.
range	float	✓	Default width for range inputs in pixels.
slider_value_min	float	✓	Minimum width for slider value display in pixels.
checkbox	float	✓	Default width for checkbox inputs in pixels.
daterange	float	✓	Default width for daterange chip triggers in pixels.

RangeDefaults

Authored overlay for RangeDefaults.

Field	Type	Optional	Description
default_min	float	✓	Default minimum value for range inputs.
default_max	float	✓	Default maximum value for range inputs.
default_step	float	✓	Default step size for range inputs.

AxisGridZeroStyle

Authored overlay for AxisGridZeroStyle. Zero-baseline gridline color and width overrides.

Field	Type	Optional	Description
color	str	✓	Color of the zero-baseline grid line; None inherits from parent axis.
width	float	✓	Width of the zero-baseline grid line in pixels; None inherits from parent axis.

DataTableRowPaddingStyle

Authored overlay for DataTableRowPaddingStyle.

Field	Type	Optional	Description
vertical	float	✓	Vertical (top/bottom) padding inside data_table rows in pixels.
horizontal	float	✓	Horizontal (left/right) padding inside data_table rows in pixels.

BarLabelsStyle

Authored overlay for BarLabelsStyle. Bar mark value-label config. Extends MarkLabelsStyle with bar-specific positions.

Field	Type	Optional	Description
visible	bool	✓	Show numeric value labels on each mark; False by default.
field	str	✓	Column to source label text from; None uses the chart's y-field.
format	str	✓	Number format string for value labels. Falls back to style.charts.axis_quantitative.format.
dx	int	✓	Horizontal pixel offset for value labels; overrides the position default.
dy	int	✓	Vertical pixel offset for value labels; overrides the position default.
font	FontStyle	✓	Value label font style (color, size, family, etc.).
position	enum: "above", "top", "middle", "middle_aligned", "bottom"	✓	Label position relative to the bar. 'above' places labels above the bar top (outside). 'top' places labels just inside the top edge. 'middle' centers labels vertically in the bar. 'middle_aligned' centers all labels at a common height (mean of bar heights / 2). 'bottom' places labels just inside the bottom edge.

StrokeStyle

Authored overlay for StrokeStyle. Stroke appearance sub-block shared across mark families.

Field	Type	Optional	Description
color	str	✓	Stroke color as a CSS color string.
width	float	✓	Stroke width in pixels.
cap	enum: "butt", "round", "square"	✓	Stroke line cap style (butt, round, or square).
join	enum: "miter", "round", "bevel"	✓	Stroke line join style (miter, round, or bevel).
dasharray	str	✓	SVG stroke-dasharray pattern (e.g. '4 2').

PointLabelsStyle

Authored overlay for PointLabelsStyle. Point/line mark value-label config. Used by both LineMarkStyle and PointMarkStyle.

Field	Type	Optional	Description
visible	bool	✓	Show numeric value labels on each mark; False by default.
field	str	✓	Column to source label text from; None uses the chart's y-field.
format	str	✓	Number format string for value labels. Falls back to style.charts.axis_quantitative.format.
dx	int	✓	Horizontal pixel offset for value labels; overrides the position default.
dy	int	✓	Vertical pixel offset for value labels; overrides the position default.
font	FontStyle	✓	Value label font style (color, size, family, etc.).
position	enum: "top", "bottom", "left", "right", "middle"	✓	Label position relative to the point. 'top' places labels above the point. 'bottom' places labels below. 'left' to the left. 'right' to the right. 'middle' centers on the point.

FontColorStrokeStyle

Authored overlay for FontColorStrokeStyle. Stroke for tick/rule marks whose color defaults to the root font color.

Field	Type	Optional	Description
color	str	✓	Stroke color. Falls back to style.font.color.
width	float	✓	Stroke width in pixels.
cap	enum: "butt", "round", "square"	✓	Stroke line cap style (butt, round, or square).
join	enum: "miter", "round", "bevel"	✓	Stroke line join style (miter, round, or bevel).
dasharray	str	✓	SVG stroke-dasharray pattern (e.g. '4 2').

AreaStackedMarkStyle

Authored overlay for AreaStackedMarkStyle. Stacked / streamgraph area recipe override: solid fill + perimeter stroke.

Field	Type	Optional	Description
opacity	float	✓	Area fill opacity (0–1) for the stacked recipe.
stroke	StrokeStyle	✓	Perimeter stroke style for the stacked recipe.
halo_multiplier	float	✓	Halo stroke width multiplier for the stacked recipe; 0 disables the halo.

SliceLabelsStyle

Authored overlay for SliceLabelsStyle. Pie labels: typography + positioning offsets for per-slice text.

Field	Type	Optional	Description
offset	float	✓	Radial offset of slice labels from the arc in pixels.
line_height	float	✓	Line height for slice labels in pixels. Reserved vertical space above the disk is line_height × <rendered lines> per row, so the same value handles 1-line, 2-line, and multi-line templates.
font	FontStyle	✓	Slice label font style overrides. Unset fields fall back to style.charts.font.
default_template	LabelsDefaultTemplate	✓	Default Jinja templates for per-slice labels when template is not authored.
template	str	✓	Jinja2 label template. Overrides default_template when authored.
where	str	✓	Jinja2 boolean filter — labels only render on rows where this is truthy.

TableRowRoleStyle

Authored overlay for TableRowRoleStyle.

Field	Type	Optional	Description
rule_width	float	✓	Rule width above rows with this role in pixels.
font	FontStyle	✓	Per-role font style override; None uses the default row font.
background	str	✓	Per-role row background color; None means no override.

SparkBarLabelStyle

Authored overlay for SparkBarLabelStyle.

Field	Type	Optional	Description
inset_x	float	✓	Horizontal inset for the spark bar label in pixels.
fill	str	✓	Label text fill color.
fill_opacity	float	✓	Label text fill opacity (0–1).
min_size	float	✓	Minimum bar fill width required to show the label in pixels.
height_offset	float	✓	Vertical offset of the label from its bar top in pixels.

DetailsArrowFontStyle

Authored overlay for DetailsArrowFontStyle. Font style for the expand/collapse arrow glyph.

Field	Type	Optional	Description
size	float	✓	Font size of the arrow glyph in pixels.

LabelsDefaultTemplate

Authored overlay for LabelsDefaultTemplate. Default Jinja templates for per-slice pie/donut labels.

Field	Type	Optional	Description
with_color	str	✓	Default per-slice label template when the chart has a color binding.
no_color	str	✓	Default per-slice label template when the chart has no color binding.

PostgresSourceConfig

Postgres source configuration.

Field	Type	Optional	Description
type	enum: "postgres"		Source type identifier.
host	str		Database host name or IP address.
dbname	str		Database name (matches dbt 'dbname').
user	str		Database user name.
password	str		Database password.
lookml_path	str	✓	Relative path to the directory of .lkml files backing this source's models.
models	dict[str, LookMLModelConfig]	✓	Named LookML model collections nested under this source.
port	int	✓	Database port number.
schema	str	✓	Default schema for queries.
sslmode	enum: "disable", "allow", "prefer", "require", "verify-ca", "verify-full"	✓	libpq SSL mode forwarded to psycopg2. None lets libpq decide its default.

SnowflakeSourceConfig

Snowflake source configuration.

Field	Type	Optional	Description
type	enum: "snowflake"		Source type identifier.
account	str		Snowflake account identifier (e.g. xy12345.us-east-1).
user	str		Snowflake user name.
database	str		Snowflake database name.
warehouse	str		Snowflake virtual warehouse name.
lookml_path	str	✓	Relative path to the directory of .lkml files backing this source's models.
models	dict[str, LookMLModelConfig]	✓	Named LookML model collections nested under this source.
password	str	✓	Snowflake password. Omit when using OAuth or key-pair auth.
schema	str	✓	Default schema for queries.
role	str	✓	Snowflake role to assume for the session.

BigQuerySourceConfig

BigQuery source configuration.

Field	Type	Optional	Description
type	enum: "bigquery"		Source type identifier.
project	str		GCP project ID.
dataset	str		BigQuery dataset name (equivalent to schema).
lookml_path	str	✓	Relative path to the directory of .lkml files backing this source's models.
models	dict[str, LookMLModelConfig]	✓	Named LookML model collections nested under this source.
keyfile	str	✓	Path to service account JSON key file.
keyfile_json	dict[str, Any]	✓	Inline service account JSON dict.
location	str	✓	Dataset location (e.g. US, EU).
method	enum: "oauth", "service-account", "service-account-json"	✓	dbt-bigquery authentication method. Inferred from keyfile/keyfile_json when omitted: 'service-account-json' if keyfile_json set, 'service-account' if keyfile set, 'oauth' (Application Default Credentials) otherwise.

RedshiftSourceConfig

Redshift source configuration.

Field	Type	Optional	Description
type	enum: "redshift"		Source type identifier.
host	str		Redshift cluster host name.
dbname	str		Redshift database name.
user	str		Redshift user name.
password	str		Redshift password.
lookml_path	str	✓	Relative path to the directory of .lkml files backing this source's models.
models	dict[str, LookMLModelConfig]	✓	Named LookML model collections nested under this source.
port	int	✓	Redshift port number.
schema	str	✓	Default schema for queries.

MySQLSourceConfig

MySQL source configuration.

Field	Type	Optional	Description
type	enum: "mysql"		Source type identifier.
host	str		MySQL host name or IP address.
database	str		MySQL database name.
user	str		MySQL user name.
password	str		MySQL password.
lookml_path	str	✓	Relative path to the directory of .lkml files backing this source's models.
models	dict[str, LookMLModelConfig]	✓	Named LookML model collections nested under this source.
port	int	✓	MySQL port number.
schema	str	✓	Default schema for queries.

DuckDBSourceConfig

DuckDB source configuration.

Field	Type	Optional	Description
type	enum: "duckdb"		Source type identifier.
lookml_path	str	✓	Relative path to the directory of .lkml files backing this source's models.
models	dict[str, LookMLModelConfig]	✓	Named LookML model collections nested under this source.
path	str	✓	DuckDB file path or ':memory:' for an in-memory database.
schema	str	✓	Default schema for unqualified table names (sets search_path).

SQLiteSourceConfig

SQLite source configuration.

Field	Type	Optional	Description
type	enum: "sqlite"		Source type identifier.
path	str		Path to the SQLite database file.
lookml_path	str	✓	Relative path to the directory of .lkml files backing this source's models.
models	dict[str, LookMLModelConfig]	✓	Named LookML model collections nested under this source.

CsvSourceConfig

CSV file source configuration.

Field	Type	Optional	Description
type	enum: "csv"		Source type identifier.
files	dict[str, str]		Mapping of table_name → file path. Each key is the SQL table name; the value is the path relative to the project root. Required and must not be empty.
delimiter	str	✓	Field delimiter character.
encoding	str	✓	File encoding.

ParquetSourceConfig

Parquet file source configuration.

Field	Type	Description
type	enum: "parquet"	Source type identifier.
files	dict[str, str]	Mapping of table_name → file path. Each key is the SQL table name; the value is the path relative to the project root. Required and must not be empty.

JsonSourceConfig

JSON file source configuration.

Field	Type	Description
type	enum: "json"	Source type identifier.
files	dict[str, str]	Mapping of table_name → file path. Each key is the SQL table name; the value is the path relative to the project root. Required and must not be empty.

HttpSourceConfig

HTTP/REST API source configuration.

Field	Type	Optional	Description
type	enum: "http"		Source type identifier.
url	str		Base URL for HTTP requests.
headers	dict[str, str]	✓	Default HTTP headers (e.g. Authorization).

DbtProfileSourceConfig

Reference to a dbt profile.

Field	Type	Optional	Description
type	enum: "dbt_profile"		Source type identifier.
profile	str		dbt profile name from profiles.yml.
target	str	✓	dbt target to use; defaults to the profile's default target.
profiles_dir	str	✓	Directory containing profiles.yml, relative to the dataface project root. Use when profiles.yml is in a subdirectory (e.g. services/dbt). Resolution order: profiles_dir → $DBT_PROFILES_DIR → project root → ~/.dbt.

VariableRef

Cross-file variable reference. Bare string is coerced automatically.

Field	Type	Description
ref	str	Reference path: '<file>.variables.<name>'. A bare string value is coerced automatically.

QueryRef

Cross-file query reference. Bare string is coerced automatically.

Field	Type	Description
ref	str	Reference path: '<file>.queries.<name>'. A bare string value is coerced automatically.

ChartRef

Cross-file chart reference. Bare string is coerced automatically.

Field	Type	Description
ref	str	Reference path: '<file>.charts.<name>'. A bare string value is coerced automatically.

LookMLModelConfig

One LookML model: a named collection of explores under a warehouse source.

Field	Type	Optional	Description
lkml	str	✓	Path to a specific .lkml model file, relative to the project root.
group_label	str	✓	LookML group_label selecting this model's explores. Not yet enforced at compile time.
explores	list[str]	✓	Explicit list of explore names in this model.