Skip to content

Single-Chart Property Gap Report

This page logs gaps, drift, and unresolved questions discovered while building the Single-Chart Property Catalog.

Use it as a working audit log, not as the final reference.

Current Gaps

Unknown top-level chart keys now fail fast

  • Evidence: ChartFields now uses strict extra handling, so both ChartPatch and CompiledChart reject unknown top-level chart fields.
  • Current finding: stale fields such as group_by, chart-level limit, interactions, key, metric, and arbitrary typos now raise validation errors instead of compiling and disappearing.
  • Action: resolved for the compile boundary. Documentation and schema surfaces should keep these fields out of chart examples unless they are reintroduced as real authored schema.

filters, href, and query limit need clearer ownership

  • Evidence: filters and href are authored chart properties; limit belongs to query definitions.
  • Current finding: older docs sometimes described row limiting as chart-level behavior.
  • Action: keep chart docs focused on filters and href; document row limiting under queries and table pagination under style.pagination.

Structured interactions are planned, not accepted schema

  • Evidence: strict chart validation rejects interactions:. Hover tooltips are renderer defaults, and click-through links use top-level href:.
  • Current finding: older docs implied the YAML schema reserved a future interactions: shape; that is no longer true.
  • Action: keep planned click-handler discussion out of concrete YAML examples until a real schema lands.

Nested surfaces are better documented than the old global field reference

  • Evidence: family pages now document style, mark, and encoding more accurately than the older global reference page
  • Current finding: Field Reference now points readers to the catalog and uses the newer property names, but smaller reference pages still need a final terminology sweep
  • Action: continue the reference-doc sweep until no chart reference page uses stale property names or stale interaction literals

style.background is now surfaced in the chart overview docs, but family pages may still lag it

  • Evidence: chart rendering wraps the final SVG with a background rectangle when chart.style.background is set, and the charts overview now lists it as a style option
  • Current finding: implementation and top-level chart docs are aligned, but family-specific pages still mostly focus on legend/grid/color-scheme examples
  • Action: decide whether every family page should repeat it or whether the overview plus catalog is sufficient

series promotion has been removed

  • Evidence: promote_series_to_y() was deleted as dead code after the settings→style merge
  • Current finding: series as a chart key no longer has any runtime behavior — list-valued y is the only supported way to specify multiple metrics
  • Action: use list-valued y in canonical examples and family docs

Table and spark_bar style fields are implementation-backed and now documented

  • Evidence: table renderer reads style.columns and style.header_overflow; spark_bar renderer reads six style overrides
  • Current finding: these fields now have explicit catalog rows and are documented in the tables family page
  • Action: resolved — all former settings.* fields are now under style.*

Validated standard mark/encoding families are now cataloged evenly, but non-Vega single-chart surfaces still need the same child-row treatment

  • Evidence: the master catalog now expands child rows for bar, line, area, point, scatter, pie, and donut
  • Current finding: filters.*, href, and the main specialized-family surfaces now have implementation-backed catalog rows, so the remaining completeness gap has shifted toward legacy/global-reference reconciliation and smaller maturity mismatches
  • Action: continue the same audit pattern until every authored single-chart property and meaningful maturity caveat has an implementation-backed row

Nested reusable schemas needed explicit structure to avoid duplication

  • Evidence: authored paths like style.axis_x and style.axis_y share the same underlying object shape, and style.columns[] was beginning to drift into duplicated child-row inventories
  • Current finding: the catalog now separates authored property rows from reusable nested schema rows, and shared schemas for AxisConfig.*, ScaleConfig.*, GeoConfig.*, MapBackgroundConfig.*, TableColumnConfig.*, and SparkConfig.* are all in place
  • Action: preserve this structure as the catalog grows and only duplicate child rows when a reused object shape is genuinely asymmetric in implementation

Final completeness risk is now concentrated in low-signal residual surfaces and reference reconciliation

  • Evidence: the final code sweep found no large uncataloged object surfaces beyond the ones already promoted into reusable schema sections
  • Current finding: the remaining uncertainty is concentrated in the exact desired scope of lightweight reference-page reconciliation and whether compatibility surfaces should be surfaced outside the catalog
  • Action: treat these as the final blockers before declaring the catalog complete, rather than continuing to hunt for new large schema families

The remaining unresolved surfaces are classification questions, not missing inventory

  • Evidence: top-level properties, nested standard-family surfaces, specialized-family rows, reusable schemas, and renderer-maturity gaps have all been audited
  • Current finding: what remains is deciding whether compatibility properties like series should appear outside the source-of-truth reference
  • Action: once that editorial decision is made, the inventory itself can reasonably be treated as complete

Default-owner classification now exists, but some boundaries are still judgment calls

  • Evidence: the catalog now includes a default owner column with chart, structure, theme, none, and n/a
  • Current finding: the hardest judgment calls are mixed or low-level passthrough surfaces, especially some mark.* leaves and whether a few framing values should be treated as chart-authored framing or reusable structure defaults
  • Action: keep refining those judgments as structure/theme policy becomes more explicit, but do not treat that as missing catalog inventory

none is now a reviewed basket, not a miscellaneous overflow bucket

  • Evidence: the current none rows are limited to mixed parent container rows and compatibility-only surfaces.
  • Current finding: this is the right shape for now because container rows mix child owners and series is compatibility-only.
  • Action: keep none intentionally small; any new none row should justify why it should stay out of both structure and theme ownership

Root-level completeness check passed apart from internal runtime fields

  • Evidence: a direct CompiledChart.model_fields comparison against the catalog found only variable_dependencies, source_path, and query_is_inline missing
  • Current finding: those three are internal runtime/compiler fields rather than authored chart properties, so they are now explicitly treated as out of scope
  • Action: keep this check in mind for future catalog updates whenever CompiledChart changes

Audit Rules

When a gap is found:

  1. Keep the property in the master catalog if code accepts it.
  2. Mark its current docs status honestly.
  3. Add a note here only if the issue needs follow-up, reconciliation, or a decision.