Field Reference¶
Complete reference of all fields available in Dataface YAML files, audited against the Pydantic models in dataface/core/compile/.
For implementation-backed chart property details, see the Single-Chart Property Catalog.
Board¶
The fundamental building block of Dataface. A Board (internally Face) is a container that defines content, layout, and data resources. Boards are recursive: a board can contain other boards.
# Board title: string # Optional: display title description: string # Optional: description tags: [string] # Optional: tags for organization text: string # Optional: markdown content (can be used with layout) # Data Sources source: string # Optional: default source name (shorthand) sources: # Optional: source configuration block default: string # Default source name for all queries # ... additional inline source definitions (name: {type: ..., ...}) # Layout (exactly one required, unless content is provided) rows: [...] # Stack items vertically cols: [...] # Stack items horizontally grid: {...} # Arrange items in a grid tabs: {...} # Organize items in tabs # Scoped Definitions variables: {...} # Optional: variable definitions queries: {...} # Optional: query definitions charts: {...} # Optional: shared chart definitions # Focus Mode chart_focus: string # Optional: render only this chart and its dependencies # Collapsible Section (details) details: string # Optional: summary text (clickable header) expanded_title: string # Optional: different text when expanded (defaults to details) expanded: boolean # Optional: default state (default: false = collapsed) # Styling & Dimensions (when nested) id: string # Optional: unique ID for referencing (e.g. "file.id") style: {...} # Optional: style overrides (StylePatch) width: string | number # Optional: explicit width (e.g. "50%", 6) height: string | number # Optional: explicit height (e.g. "400px", 4) theme: string # Optional: Vega-Lite theme (e.g. "dark", "fivethirtyeight") style_preset: string # Optional: geometry/layout/composition preset name card_gap: boolean # Optional: render layout items as separated cards with a visible gap (default: false)
Layout Configuration¶
Grid Configuration¶
Used when the grid: key is present.
grid: columns: number # Required: number of columns (e.g., 12) row_height: string # Optional: height of rows (e.g., "100px") gap: string # Optional: gap size (sm, md, lg, xl) default_width: number # Optional: default column span for items default_height: number # Optional: default row span for items items: # Required: list of grid items - item: string | Board | Chart # The content to place description: string # Optional: metadata for AI search/tooltips col: number # Optional: column position (0-indexed) row: number # Optional: row position (0-indexed) col_span: number # Optional: number of columns to span row_span: number # Optional: number of rows to span width: number # Optional: alias for col_span height: number # Optional: alias for row_span
Tab Configuration¶
Used when the tabs: key is present.
tabs: id: string # Optional: variable name + URL param base position: top | left # Optional: tab bar position (default: top) default: string # Optional: default tab title to select items: # Required: list of tabs - title: string # Required: tab label icon: string # Optional: icon name description: string # Optional: metadata for AI search/tooltips text: string # Optional: markdown content style: {...} # Optional: style overrides # ... plus any Board layout properties (rows, cols, grid, tabs)
Chart¶
Charts visualize data. They can be defined inline within a layout or in the charts: definition block.
# Identity & Metadata id: string # Optional: set during compilation title: string # Optional: display title subtitle: string # Optional: subtitle text type: string # Optional: chart type (bar, line, pie, kpi, table, etc.) query: string | {...} # Optional: query name reference or inline query description: string # Optional: help text/tooltip # Data Mapping — General x: string # Optional: x-axis field y: string | [string] # Optional: y-axis field(s) color: string # Optional: color encoding field size: string # Optional: size encoding field shape: string # Optional: shape encoding field # Axis Labels x_label: string # Optional: custom x-axis label y_label: string # Optional: custom y-axis label # Arc Charts (pie/donut) theta: string # Optional: theta (angle) encoding field # KPI Charts (quantitative text object: value / label / optional support) value: string | number # Required for KPI: column reference OR literal scalar. # String matching a column name in the bound query # result is treated as a column reference; everything # else is a literal (numeric or string). label: string # Optional: text rendered above the headline value. # KPI uses `label:` (not `title:`) — `title:` is # rejected on KPI; `label:` is rejected on every # other chart type. glyph: string # Optional: prefix glyph (e.g. "▲", "●") tone: positive | negative | neutral | warning # Optional: semantic tone for value/glyph value_color: string # Optional: explicit value color (overrides tone) glyph_color: string # Optional: explicit glyph color (overrides tone) support: # Optional: support line under the value (same shape) value: string | number label: string # Trailing explainer text (rendered neutral) format: {...} # Same FormatConfig as the main format glyph: string tone: positive | negative | neutral | warning value_color: string glyph_color: string format: # Optional: value formatting (KPI defaults to editorial) spec: string # D3 format string, preset, or Excel pattern prefix: string # Custom prefix (e.g. "$") suffix: string # Custom suffix (e.g. " USD") notation: bi | editorial # Number notation style (KPI default: editorial) # bi: k/M/B/T — d3-aligned, tilde-trimmed, B for billion (not G) # editorial: k/mn/bn/tr — newspaper-style, no space # format: string # Shorthand: just the spec string # Map Charts (map, geoshape; choropleth is an alias for map) geo: string | {...} # Optional: TopoJSON feature (name or inline config) geo_source: string # Optional: geographic data source reference lookup: string # Optional: field to join data to geo features # Map fill column reuses the `value:` field above (KPI/map share the binding). projection: string | {...} # Optional: map projection (name or config) # Point/Bubble Map Charts latitude: string # Optional: latitude field longitude: string # Optional: longitude field background: {...} # Optional: map background layer config # Layered Charts (mixed-mark composition) layers: # Required for type: layered - type: string # Required: mark type (bar, line, area, etc.) query: string # Optional: per-layer query for multi-query layers x: string # Optional: per-layer x field (overrides parent) y: string # Required: y-axis field for this layer color: string # Optional: color encoding (overrides parent) size: string # Optional: size encoding (overrides parent) shape: string # Optional: shape encoding (overrides parent) # Ordering sort: # Optional: categorical axis sort by: string # Field to sort by order: asc | desc # Sort direction (default: asc) # Links and filters href: string # Optional: click-through URL template. Channel # placeholders {{ x }}, {{ y }}, {{ color }}, # {{ theta }} are substituted per clicked row. # See charts/interactions.md. Not used by tables # (use column-level `link:` on table columns). filters: {...} # Optional: chart-level filter conditions # Chart-Local Style style: {...} # Optional: ChartStylePatch (see Styling section)
Row limiting and grouping are query responsibilities. Use query SQL, MetricFlow
dimensions, or queries.<id>.limit instead of chart-level group_by or limit
fields.
Supported Chart Types¶
| Type | Description | Key Fields |
|---|---|---|
bar |
Bar chart | x, y, color |
line |
Line chart | x, y, color |
area |
Area chart | x, y, color |
scatter (alias: point) |
Scatter plot | x, y, color, size |
circle |
Circle marks | x, y, size |
square |
Square marks | x, y, size |
pie / donut |
Arc charts | theta, color |
kpi |
Quantitative text object (value / label / optional support) | value, label, support, format |
table |
Data table | style.columns |
heatmap |
Heatmap (→ rect) | x, y, color |
histogram |
Histogram (→ bar + binning) | x |
map (alias: choropleth) |
Filled map | geo, lookup, value, projection |
point_map / bubble_map |
Point map | latitude, longitude, size |
boxplot |
Box plot | x, y |
tick |
Strip/tick plot | x, y |
rule |
Reference lines | x, y |
trail |
Trail (varying width) | x, y, size |
rect |
Rectangle marks | x, y, color |
arc |
Arc marks | theta, color |
geoshape |
Geographic shapes | geo, projection |
image |
Image marks | — |
errorbar / errorband |
Uncertainty | x, y |
spark_bar |
Compact inline bars | — |
auto |
Auto-detect (internal) | — |
Layered charts may use one shared query or per-layer query: values. When
multiple layers come from different queries but their x fields are already
identical, or are recognized as equivalent temporal/date axes, Dataface treats
them as one shared x-axis layered chart. This is an encoding-level auto-merge
for compatible x axes, not a query-side join or data reshape.
Table Column Configuration¶
Table charts use style.columns to configure individual columns:
style: columns: - column: string # Required: column name from query result label: string # Optional: custom header label format: string | {...} # Optional: D3 format string or FormatConfig width: number | string # Optional: column width (px or %) align: left | center | right # Optional: text alignment header_link: string # Optional: link URL for header spark: # Optional: inline spark chart type: string # line | area | bars | progress | histogram color: string # Primary color (CSS) height: number # Height in pixels (default: 24) width: number # Width in pixels (default: 80) show_last: boolean # Show dot on last value (line/area) show_min_max: boolean # Show dots on min/max (line/area) fill_opacity: number # Fill opacity 0.0–1.0 (area) max: number # Maximum value (progress, default: 100) thresholds: {...} # Color thresholds (progress, e.g. {50: "yellow"}) background: string # Background color (progress) border_radius: number # Border radius (progress) show_value: boolean # Show value text (progress) value_suffix: string # Suffix for value text (progress) # spark: line # Shorthand: just the spark type
Query¶
Queries define how to fetch data. The type is inferred from the fields present — you rarely need to set it explicitly.
SQL Query¶
String shorthand — when a face-level source: is set, a bare SQL string is sufficient:
source: my_db queries: my_query: string # bare SQL; inherits face-level source
Dict form — use when overriding source, setting target, or adding description:
queries: my_query: sql: string # Required: SQL query (supports Jinja templates) source: string | {...} # Required if no face-level source target: string # Optional: dbt target name (default: "dev") description: string # Optional: metadata for AI search/tooling filters: {...} # Optional: filter conditions limit: number # Optional: maximum rows
MetricFlow Query¶
queries: my_metrics: type: metricflow # Required for MetricFlow metrics: [string] # Required: list of metric names dimensions: [string] # Optional: list of dimension names time_grain: string # Optional: day | week | month | quarter | year description: string # Optional: metadata filters: {...} # Optional: filter conditions limit: number # Optional: maximum rows
dbt Model Query¶
queries: my_model: model: string # Required: dbt model reference columns: [string] # Optional: columns to select (default: all) description: string # Optional: metadata filters: {...} # Optional: filter conditions limit: number # Optional: maximum rows
HTTP Query¶
queries: api_data: type: http # Required for HTTP url: string # Full URL (legacy) — or use source + path source: string | {...} # Optional: HTTP source reference path: string # Optional: API path (appended to source base URL) method: GET | POST | PUT | DELETE | PATCH # Optional: HTTP method (default: GET) headers: {...} # Optional: request headers params: {...} # Optional: query parameters body: {...} | string # Optional: request body (POST/PUT/PATCH) json_path: string # Optional: JSONPath to extract data from response description: string # Optional: metadata filters: {...} # Optional: filter conditions limit: number # Optional: maximum rows
CSV Query¶
queries: csv_data: type: csv # Required for CSV (or use source) file: string # File path (relative to project root or absolute) source: string | {...} # Optional: CSV source reference columns: [string] # Optional: columns to select filter: {...} # Optional: column→value exact match filters delimiter: string # Optional: field delimiter encoding: string # Optional: file encoding description: string # Optional: metadata filters: {...} # Optional: filter conditions limit: number # Optional: maximum rows
Values Query (Inline Data)¶
queries: inline_data: type: values # Required for inline data # Option A: dict rows (verbose) rows: - {month: "Jan", revenue: 100} - {month: "Feb", revenue: 140} # Option B: columns + values (compact) columns: [month, revenue] values: - ["Jan", 100] - ["Feb", 140] description: string # Optional: metadata filters: {...} # Optional: filter conditions limit: number # Optional: maximum rows
Variable¶
Variables provide dynamic values to queries and charts. They can be bound to user inputs or have static defaults.
variables: my_var: input: string # Optional: input type (auto-detected when omitted; see table below) label: string # Optional: display label description: string # Optional: helper text default: any # Optional: default value placeholder: string # Optional: placeholder text required: boolean # Optional: is value required? (default: false) allow_null: boolean # Optional: allow null values? (default: false) hidden: boolean # Optional: hide from UI (default: false) disabled: boolean | string | {query: string, column: string} # Optional: disable this control. Three forms: # disabled: true # static bool # disabled: "{{ x != 'A' }}" # Jinja expression # disabled: # query-backed # query: my_query # column: is_disabled # Filter Operator operator: string # Optional: operator for filter generation (e.g. "=", "in") # Options (for select/multiselect) options: static: [string | number] # List of static values query: string # Query name to fetch options dynamically column: string # Column name for option values label_column: string # Optional: column for display labels # Direct Source Binding (alternative to options) column: string # Optional: bind to a column directly query: string | {...} # Optional: query reference or inline query dimension: string # Optional: MetricFlow dimension measure: string # Optional: MetricFlow measure model: string # Optional: dbt model # Slider/Range Specific min: number # Optional: minimum value max: number # Optional: maximum value step: number # Optional: step increment
Input Types¶
When input is omitted (or set to auto), the compiler auto-detects the type from the other fields present:
Rules are checked in priority order (first match wins):
| Signal | Inferred Type |
|---|---|
default is a list |
multiselect |
min, max, or step present |
slider |
default is a boolean |
checkbox |
options.static or options.query |
select |
column only |
select |
hidden: true with no other signals |
text |
| No signals | text |
You can always set input explicitly to override auto-detection:
| Type | Description |
|---|---|
select |
Single-value dropdown |
multiselect |
Multi-value dropdown |
input / text |
Single-line text input |
number |
Numeric input |
textarea |
Multi-line text input |
slider |
Numeric slider (use min, max, step) |
range |
Numeric range slider |
date / datepicker |
Date picker |
daterange |
Date range picker |
checkbox |
Boolean checkbox |
radio |
Radio button group |
Disabled State¶
The disabled field renders the control visually disabled and prevents user interaction. Three authoring forms:
Static boolean — always enabled or always disabled:
initial_live_cells: input: text disabled: true
Jinja expression — evaluated against current variable values each render:
initial_live_cells: input: text disabled: "{{ starter_pattern != 'Random' }}"
Variables referenced in the expression are tracked as dependencies so the control re-evaluates when they change.
Query-backed — reads a single boolean cell from a named query:
seed_control: input: text disabled: query: seed_state column: is_disabled
The query must return exactly one row. The named column must hold a value coercible to bool (true/false/1/0/yes/no). If the query is missing, returns no rows, returns multiple rows, points at a missing column, or returns a non-boolean value, an error is raised.
Foreach¶
The foreach construct dynamically generates layout items by iterating over inline data.
# Foreach (within rows/cols) - foreach: query: # Required: data source data: [...] # Required: inline data array as: string # Required: loop variable name items: [...] # Required: items to generate per iteration
Fields¶
| Field | Type | Required | Description |
|---|---|---|---|
query |
object | Yes | Contains data array to iterate over |
as |
string | Yes | Variable name for each row (e.g., item) |
items |
list | Yes | Layout items to generate per iteration |
Example¶
rows: - foreach: query: data: - name: "Revenue" type: "numeric" - name: "Date" type: "date" as: col items: - title: "{{ col.name }}" text: "Type: {{ col.type }}"
See Board Imports for more examples.
Styling¶
Dataface uses a layered style system. Board-level style sets theme defaults; chart-level style overrides per chart. Sub-style sections below show representative fields; see the Pydantic models in compile/style_model.py for the full surface.
Board-Level Style (StylePatch)¶
style: charts: # Chart rendering theme # Top-level background: string # SVG background fill font: string # Font family padding: number | {...} # Chart padding number_format: string # Default number format time_format: string # Default time format # Axis (also: axis_x, axis_y, axis_band, axis_quantitative) axis: grid: hidden: boolean # Hide grid lines color: string # Grid line color width: number # Grid line width domain: hidden: boolean # Hide axis domain line label: size: number # Label font size color: string # Label color title: size: number # Axis title font size # ... see AxisStyle for full list axis_x: time_unit: yearmonth # Temporal bucket for x encoding label: time_unit: yearquarter # Optional label cadence override # Legend legend: disable: boolean # Hide legend orient: string # Legend position # ... see LegendStyle for full list # Title title: overflow: string # clip | truncate | wrap-two | wrap # Per-chart-type authored overlay (CompiledBarStylePatch, CompiledLineStylePatch, etc.) bar: padding: number # Band padding ratio (0–1) stroke: string # Bar outline color stroke_width: number # Bar outline width size: number # Bar width on continuous scales (continuousBandSize) line: stroke_width: number # Line width curve: string # Interpolation (linear | monotone | step | ...) point_size: number # Point marker size (0 = hidden) area: opacity: number # Fill opacity (0–1) stroke_width: number # Stroke width # Scale & Range scale: {...} # Scale defaults (ScaleStyle) range: category: [string] # Categorical color palette diverging: [string] # Diverging color palette heatmap: [string] # Heatmap color palette ramp: [string] # Sequential color ramp # Chart-specific presentation orientation: horizontal | vertical stack: boolean | zero | normalize | center palette: string # Named color palette columns: [...] # Table column configs header_overflow: string # Table header overflow mode # Spark-bar overrides (nested) spark_bar: max_bars: number # Maximum number of bars labels_hidden: boolean # Hide bar labels counts_hidden: boolean # Hide count values bar_height: number # Bar height in pixels bar_color: string # Bar fill color bar_background: string # Bar background color # Non-Vega sections table: {...} # Table renderer style (TableStyle) kpi: {...} # KPI renderer style (KpiStyle) inference: {...} # Chart inference defaults (CompiledInferenceStylePatch) pagination: # Table pagination config (PaginationConfig) enabled: boolean # Toggle pagination (default: true) page_size: number # Rows per page (positive integer) # pagination: 25 # Shorthand: page_size (enabled implied) # pagination: true # Shorthand: enabled, default page_size markdown: # Markdown rendering theme light: text_color: string heading_color: string link_color: string code_color: string code_background: string blockquote_color: string dark: # ... same fields as light
Chart-Level Style (ChartStylePatch)¶
Chart-level style uses the same structure as style.charts above, plus:
style: border_radius: number # Chart border radius color_scheme: string # Map color scheme override pagination: # Table pagination (PaginationConfig) enabled: boolean # Toggle pagination (default: true) page_size: number # Rows per page (positive integer) # pagination: 25 # Shorthand: page_size (enabled implied) # ... plus all ChartStylePatch fields (background, legend, axis, etc.)
Interaction¶
Coming Soon
Structured interactions: are not part of the authored chart schema. Hover tooltips work automatically. For click-through links, use chart-level href: with a URL field or template.
href: detail_url # field containing per-row URLs # or href: "/orders/{{ order_id }}" # template using row/channel values