Single-Chart Property Catalog¶

This is the working source-of-truth inventory for the authored control surface of a single Dataface chart.

A chart's control surface is the full set of authored properties available on a single chart. In YAML hierarchy terms, those properties can appear at the root, branch, or leaf level.

This catalog intentionally focuses on the currently supported authored Dataface surface:

top-level semantic and channel fields such as type, x, y, color, theta, and format
typed nested Dataface surfaces such as style.* and filters.* (arbitrary Vega-Lite config, transform, params, and composition blocks are rejected)

Chart-level mark and encoding are not part of the authored Dataface surface.

See the Single-Chart Property Catalog Schema for build rules and completeness checks, and the Single-Chart Property Gap Report for mismatches or underdocumented surface area discovered during the audit.

For empirical control-surface checks, see the Chart Property Diagnostics Guide.

Catalog Structure¶

The catalog uses two complementary row types:

Authored property rows record the exact YAML path a chart author writes, such as style.axis_x or style.columns.
Reusable nested schema rows record shared object shapes once, such as AxisConfig.*, ScaleConfig.*, TableColumnConfig.*, and SparkConfig.*.

We use root, branch, and leaf for YAML depth:

Root: a property directly on the chart object, such as x or style
Branch: an intermediate property path such as style.axis_x
Leaf: a final value-bearing property such as SparkConfig.color

Catalog Status¶

Pass	Status	Notes
Pass 1. Raw inventory	In progress	Top-level and `style.*` rows captured
Pass 2. Normalize and classify	In progress	Initial row schema applied across the current authored surface
Pass 3. Cross-check docs/examples/tests	In progress	Runtime and schema mismatches reduced; remaining gaps logged separately
Pass 4. Publish complete catalog	In progress	Major authored surfaces are cataloged; remaining work is deeper classification of lower-maturity families

Support Classification¶

When a property is real but not equally mature, the catalog uses three classifications in the notes:

Canonical: a first-class authored property we expect people to use directly
Compatibility: an accepted shorthand, repair path, or alias that is still real but not the preferred canonical authoring path
Low-maturity accepted surface: accepted by code and kept in the catalog, but not yet backed by meaningful single-chart runtime behavior

Default Owner¶

The default owner column describes where the default should primarily live when the property is reused or centralized:

chart: chart-authored by default
structure: scaffold/default-layout behavior
theme: visual styling default
none: intentionally not owned by chart presets, themes, or structures as a reusable default
n/a: derived behavior row, not an authored property

Top-Level Properties¶

Property path	Surface	Family scope	Default owner	Kind	Maps to	Allowed values	Authored status	Notes
`query`	`top_level`	all authored charts	`chart`	semantic	data source binding	query reference or inline query object	authored	Required in practice for most real charts.
`type`	`top_level`	all	`chart`	semantic	Vega-Lite mark family or Dataface chart family	chart type literal such as `bar`, `line`, `area`, `scatter`, `pie`, `table`, `kpi`, `map`, `point_map`, `bubble_map`, `auto`, and other supported mark types. `point` is an alias for `scatter`; `choropleth` is an alias for `map`; `donut` is an alias for `pie` with `inner_radius: 0.5`.	authored	`auto` remains semantic intent rather than a concrete rendered family.
`title`	`top_level`	all	`chart`	presentation	chart title handling	string	authored	Present across Vega-Lite and non-Vega renderers.
`description`	`top_level`	all	`chart`	presentation	metadata and rendered description/title attributes	string	authored	Used for tooling and accessible metadata more than geometry.
`x`	`top_level`	axis, point, and some specialized charts	`chart`	binding	`encoding.x.field` or equivalent positional binding	field name	authored	Invalid for pie top-level surface.
`y`	`top_level`	axis, point, and some specialized charts	`chart`	binding	`encoding.y.field` or equivalent positional binding	field name or list of field names	authored	List-valued `y` enables layered multi-metric patterns for some families.
`color`	`top_level`	many families	`chart`	binding	`encoding.color.field`	field name	authored	Family meaning varies by chart type.
`size`	`top_level`	point, scatter, bubble map, and size-aware families	`chart`	binding	`encoding.size.field`	field name	authored	Forbidden for explicit line and pie top-level surfaces.
`shape`	`top_level`	point/scatter and shape-aware families	`chart`	binding	`encoding.shape.field`	field name	authored	Primarily meaningful for point-family charts.
`theta`	`top_level`	pie and arc-like families	`chart`	binding	`encoding.theta.field`	field name	authored	Sector-family primary numeric binding.
`x_label`	`top_level`	axis and point families	`chart`	presentation	`encoding.x.title`	string	authored	High-level shorthand for axis title override.
`y_label`	`top_level`	axis and point families	`chart`	presentation	`encoding.y.title`	string	authored	High-level shorthand for axis title override.
`label`	`top_level`	KPI charts	`chart`	presentation	Dataface KPI label text	string	authored	KPI-only text rendered above the headline value. `title` is rejected on KPI charts.
`format`	`top_level`	quantitative charts and KPI	`chart`	presentation	value formatting	format string or `FormatConfig`	authored	Interacts with `style.axis_y.format` and `style.scale.zero` during semantic resolution.
`geo`	`top_level`	map families	`chart`	semantic	geographic source config	string or object	authored	Primary top-level map source config.
`geo_source`	`top_level`	map families	`chart`	semantic	built-in geographic source selector	built-in source name	authored	Convenience shorthand that overlaps with `geo`.
`lookup`	`top_level`	map and joined geography charts	`chart`	binding	geoshape lookup join key	field name	authored	Exact-key matching behavior matters.
`value`	`top_level`	KPI and map fill cases	`chart`	binding	KPI value selection or region fill field	field name, number, or string literal	authored	KPI uses `value` for the headline value; map uses it for region fill semantics.
`projection`	`top_level`	map families and projection-aware charts	`chart`	semantic	top-level Vega-Lite projection	projection name or object	authored	Primarily relevant to map-family rendering and projection overrides.
`latitude`	`top_level`	`point_map` and `bubble_map` families	`chart`	binding	`encoding.latitude.field`	field name	authored	Top-level latitude is map-specific.
`longitude`	`top_level`	`point_map` and `bubble_map` families	`chart`	binding	`encoding.longitude.field`	field name	authored	Top-level longitude is map-specific.
`background`	`top_level`	map families	`chart`	presentation	map background layer config	object	authored	Map-specific authored surface.
`href`	`top_level`	Vega-Lite-backed row-mark charts	`chart`	behavior	`encoding.href`	URL field or template string	authored	Click-through link surface. Structured `interactions:` are not part of the authored chart schema.
`sort`	`top_level`	ordered chart families	`chart`	semantic	categorical axis sort behavior	sort object	authored	Forbidden for explicit pie/donut top-level surface.

`style.*` Properties¶

Property path	Surface	Family scope	Default owner	Kind	Maps to	Allowed values	Authored status	Notes
`style`	`style`	many families	`none`	container	typed chart-style patch	object	nested_authored	Parent style container.
`style.legend.disable`	`style`	charts that encode `color`	`structure`	presentation	legend visibility	boolean	nested_authored	Canonical authored legend toggle.
`style.axis.grid`	`style`	axis-based charts	`structure`	presentation	grid visibility	boolean	nested_authored	Typed grid control.
`style.background`	`style`	many families	`theme`	presentation	chart SVG background wrapper	color value	nested_authored	Applied after SVG rendering as a wrapper rectangle.
`style.color_scheme`	`style`	`map`	`theme`	presentation	color scale scheme	Vega-Lite color scheme name	nested_authored	Specialized map color-scale override.

`filters.*` Properties¶

Property path	Surface	Family scope	Default owner	Kind	Maps to	Allowed values	Authored status	Notes
`filters`	`filters`	many families	`chart`	semantic	executor-side row filtering	object	nested_authored	Variables resolve first, then exact-match AND logic is applied against returned rows.

Specialized Family Rows¶

Property path	Surface	Family scope	Default owner	Kind	Maps to	Allowed values	Authored status	Notes
`x`	`top_level`	`histogram`	`chart`	binding	histogram bin field	field name	authored	Histogram-specific meaning differs from ordinary bar charts because the field is binned.
`value`	`top_level`	`map`	`chart`	binding	region fill field	field name	authored	Map-family specialized semantic.
`latitude`	`top_level`	`point_map`, `bubble_map`	`chart`	binding	`encoding.latitude.field`	field name	authored	May be auto-detected from common names when omitted.
`longitude`	`top_level`	`point_map`, `bubble_map`	`chart`	binding	`encoding.longitude.field`	field name	authored	May be auto-detected from common names when omitted.

Reusable Nested Schemas¶

These reusable schema families are still part of the authored surface, even when their child rows are shared instead of duplicated under every authored path:

AxisConfig.*
ScaleConfig.*
TableColumnConfig.*
SparkConfig.*

Derived Behavior Rows To Track In Later Passes¶

These are not authored top-level properties, but they already need to be reserved in the catalog because they materially affect how authored chart properties behave.

Property path	Surface	Default owner	Notes
`derived.format_inference`	`derived_behavior`	`n/a`	`format` may become `"auto"` in the intent layer and be inferred from data-aware enrichment.
`derived.zero_inference`	`derived_behavior`	`n/a`	Zero-baseline behavior is currently mediated through `style.scale.zero` and enrichment, not a separate authored top-level property.
`derived.type_inference`	`derived_behavior`	`n/a`	`type: auto` can resolve to a concrete chart family based on data shape and partial authored intent.
`derived.top_level_vs_nested_precedence`	`derived_behavior`	`n/a`	Some semantic behavior comes from both top-level shorthand and nested properties, especially formatting and explicit chart-family validation.
`derived.chart_background_wrapper`	`derived_behavior`	`n/a`	`style.background` is applied after SVG rendering as a wrapper rectangle rather than as a Vega-Lite-native spec property.
`derived.series_promotion`	`derived_behavior`	`n/a`	Compatibility preprocessing rewrites `series` into list-valued `y` before field-name resolution and semantic enrichment.
`derived.chart_level_filter_resolution`	`derived_behavior`	`n/a`	Chart-level `filters` resolve variables first, then apply exact-match AND logic against returned rows in the executor.
`derived.tooltip_defaults`	`derived_behavior`	`n/a`	Hover tooltips are generated by the renderer; there is no authored `interactions.hover` schema.
`derived.preaggregated_plot_key_requirement`	`derived_behavior`	`n/a`	`bar`, `line`, `area`, `arc`, and `heatmap`-like families reject duplicate plotted keys and expect pre-aggregated data at render time.
`derived.histogram_auto_binning`	`derived_behavior`	`n/a`	`histogram` bins the authored `x` field automatically and always renders count on the Y axis.
`derived.point_map_field_autodetection`	`derived_behavior`	`n/a`	`point_map` and `bubble_map` auto-detect latitude/longitude fields from common names when top-level bindings are omitted.

Next Passes¶

Expand reusable nested schema inventories such as AxisConfig.*, ScaleConfig.*, TableColumnConfig.*, and SparkConfig.*.
Continue classifying specialized families and compatibility surfaces.
Cross-check examples and docs against the reduced authored surface so auxiliary guides stay aligned.