Skip to content

Single-Chart Property Catalog Schema

This page defines how we build and maintain the Single-Chart Property Catalog so it stays complete, auditable, and consistent.

The catalog tracks the full authored control surface for a single 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.

Scope

The catalog includes:

  • All authored top-level chart properties accepted on a single chart
  • Nested chart properties under style, mark, and encoding
  • Chart-family-specific properties for maps, KPI, tables, sparks, and other specialized chart types
  • Aliases and shorthand surfaces such as scatter -> point and donut -> arc
  • Important precedence and inference behavior when it materially affects authored behavior

The catalog excludes:

  • Board/layout properties such as rows, cols, grid, and tabs
  • Theme files as their own separate authoring surface
  • Internal-only runtime fields that authors cannot set directly

Source Order

Every property row should be grounded in at least one implementation source, using this priority order:

  1. Implementation types and compiled models
  2. Rendering pipeline and renderer property reads
  3. Validation and chart-type surface guards
  4. Serialization and exported Dataface JSON shape
  5. Existing docs, examples, and tests

Primary source files for pass one:

  • dataface/core/compile/compiled_types.py
  • dataface/core/compile/types.py
  • dataface/core/render/chart/pipeline.py
  • dataface/core/render/chart/standard_renderer.py
  • dataface/core/render/chart/vega_lite_types.py
  • dataface/core/render/chart/geo.py
  • dataface/core/render/chart/serialization.py
  • dataface/core/defaults/default_config.yml
  • dataface/core/render/chart/DESIGN.md

Row Schema

The catalog has two row families:

  1. Authored property rows These are exact YAML property paths such as x, style.axis_x, or style.columns.

  2. Reusable nested schema rows These define shared object shapes that can sit underneath multiple authored paths, such as AxisConfig.*, ScaleConfig.*, TableColumnConfig.*, or SparkConfig.*.

This lets the catalog stay complete without duplicating the same child-property inventory under every path that reuses the same object shape.

Each row in the master catalog should include these fields:

Column Meaning
property_path Exact authored property path such as x, style.axis_x, or a reusable schema path such as AxisConfig.labelColor
row_family authored_property, nested_schema, or derived_behavior
surface One of top_level, style, mark, encoding, or derived_behavior
family_scope Chart families where the property is meaningful or accepted
default_owner Where the default should primarily live: chart, structure, theme, none, or n/a for derived rows
kind semantic, binding, presentation, passthrough, alias, interaction, filter, or derived
maps_to Vega-Lite field/concept or Dataface-only behavior
allowed_values Concise value shape or allowed literal set
authored_status authored, nested_authored, or derived_from_other_authored_properties
default_behavior What happens if the author omits it
precedence_rules Override, alias, or inference rules that affect interpretation
nested_schema Reusable object schema used by this authored path, if applicable
used_by Authored paths that consume a reusable nested schema row
source_of_truth Implementation file(s) that justify the row
docs_status documented, partially documented, undocumented, or docs drift
example_status Whether it appears in docs examples today
notes Important caveats, family restrictions, or validation rules

Support Classification

In addition to the normal row fields, the catalog should make the support level explicit in the row text or notes:

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

Examples:

  • y is canonical
  • series (compatibility) is compatibility
  • removed or planned fields such as group_by and interactions are not catalog rows unless code accepts them again

Default Owner Rules

Use the default_owner column to record where the reusable default should live, not whether a chart author is allowed to override it.

  • chart: chart-authored meaning or per-chart framing, such as x, y, color, theta, filters, or explicit scale domains
  • structure: scaffold defaults, existence decisions, posture, placement, or sizing defaults
  • theme: paint, palette, color, typography, or other visual styling defaults
  • none: intentionally kept out of reusable structure/theme assignment, usually because the property is compatibility-only, low-maturity, or too awkward/specific to centrally own well
  • n/a: derived-behavior rows that are not authored properties

Example Pattern

Use authored rows for:

  • style.axis_x
  • style.axis_y

Then define the shared child inventory once as:

  • AxisConfig.format
  • AxisConfig.labelColor
  • AxisConfig.tickCount

And connect them like this:

  • style.axis_x has nested_schema = AxisConfig
  • style.axis_y has nested_schema = AxisConfig
  • AxisConfig.* rows have used_by = style.axis_x, style.axis_y

Only duplicate child rows when the reused object shape is not actually symmetric in implementation or default behavior.

Build Passes

Pass 1. Raw Inventory

Create a row for every authored property candidate found in the implementation, without editorial cleanup.

Pass 2. Normalize

Assign each row a consistent surface, family_scope, kind, and docs_status.

Pass 3. Cross-Check

Compare the implementation-derived inventory against:

Pass 4. Publish

Maintain two outputs:

  • The exhaustive master catalog
  • A narrative guide organized by user intent, if needed later

Completeness Checks

The catalog is not complete until all of the following are true:

  1. Every authored field on CompiledChart appears in the catalog or is explicitly marked out of scope.
  2. Every chart property read in renderers or validators maps to a row.
  3. Every chart-family page can be reconciled against the catalog.
  4. Every implementation-only property is either documented or logged in the gap report.
  5. Every precedence or inference rule that changes authored behavior is captured in notes.
  6. Every non-canonical or low-maturity accepted surface is explicitly classified rather than left ambiguous.

Naming Rules

Use these terms consistently:

  • Control surface: the full set of authored properties available on a single chart
  • Property: one configurable item within that control surface
  • Property path: the exact authored key such as style.legend
  • Root: a property authored directly on the chart object, such as x or style
  • Branch: a property that contains or sits within other properties, such as style.axis_x or style.columns[]
  • Leaf: a final value-bearing property such as TableColumnConfig.label or AxisStyle.label_color
  • Channel: only for encoding.*
  • Mark property: only for mark.*

Working Notes

  • The master catalog should favor completeness over elegance.
  • If a property is accepted by code but awkward, legacy-looking, or underdocumented, keep it in the catalog and flag it rather than silently omitting it.
  • When a property is effectively family-restricted by validation, record that restriction in family_scope and notes.