Defines questions, fields, meanings, calculations, scope, interpretation, and user-visible evidence for chart specification, so adopters can represent a chart as validated, portable data and visual semantics that remain consistent with the metric and compar...
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
For Chart specification, define the semantic measurement contract so adopters can represent a chart as validated, portable data and visual semantics that remain consistent with the metric and comparison contracts. The specification selects and describes a visualization; it does not alter metric values, infer missing data, or execute arbitrary rendering code. This is a reference contract: database products, numeric budgets, jurisdictions, retention, organizational defaults, and accountable owners remain explicit adoption choices.
Scope
- The Chart specification actors, inputs, outputs, states, versions, and externally visible outcomes needed to represent a chart as validated, portable data and visual semantics that remain consistent with the metric and comparison contracts.
- The role-specific focus of this block: define the semantic measurement contract, including primary, cached, asynchronous, export, support, and recovery paths where applicable.
- Adoption-specific configuration, ownership, rollout, evidence retention, and review responsibilities needed to use the contract safely.
Outside this block
- The specification selects and describes a visualization; it does not alter metric values, infer missing data, or execute arbitrary rendering code.
- Choosing a universal database, model, renderer, vendor, numeric threshold, retention period, timezone, jurisdiction, or service-level objective.
- Claiming that packaged scenarios ran against a downstream implementation or that this reference grants security, privacy, accessibility, analytical, or legal approval.
Contract
- The declared Chart specification contract requires this rule: The agent emits a constrained chart schema, never executable JavaScript, HTML, template expressions, remote URLs, or renderer-specific escape hatches.
- The declared Chart specification contract requires this rule: Chart type follows the analytical question and data shape: time series for change over time, bars for categorical comparison, and tables when exact values dominate.
- The declared Chart specification contract requires this rule: Every encoding names field, type, unit, aggregation status, sort, scale, baseline, and result ID; the renderer does not guess semantics from column names.
- The declared Chart specification contract requires this rule: Primary and comparison series use consistent intervals, grains, units, and missing-value rules inherited from the resolved metric query.
- The declared Chart specification contract requires this rule: Axes, legends, titles, annotations, and tooltips use registered display names and plain descriptions rather than internal identifiers.
- The declared Chart specification contract requires this rule: Truncated axes, logarithmic scales, stacked totals, dual axes, smoothing, sampling, and normalization require explicit visible disclosure.
- The declared Chart specification contract requires this rule: Every chart has a concise text summary and an accessible data table or long description containing essential values, relationships, and trends.
- The declared Chart specification contract requires this rule: The renderer validates schema version, field references, row limits, color safety, and output size before producing the visual artifact.
Implementation guidance
- Begin with the business question and the decisions it informs, then specify semantic fields before choosing storage or visualization technology.
- Review terminology with a domain owner, a data owner, and representative non-specialist users before marking the definition active.
- Version every meaning-bearing field and retain a fixture that can be recalculated independently of the implementation.
- Map each displayed or spoken claim to the exact semantic field that supplies it.
Failure handling and safeguards
- For Chart specification, An unsupported chart type or unknown field returns a structured rendering error and a table fallback without executing embedded content.
- For Chart specification, Mixed units, incomparable series, or misleading scale choices block the chart and retain the validated analytical result for repair.
- For Chart specification, If the visualization is unavailable, the same result remains accessible as KPI text, a data table, and a plain-language summary.
Verification and operations
- For the analytics evidence of Chart specification, validate chart documents against the declared schema and reject code, external resources, undeclared fields, and excessive result sizes.
- For the analytics evidence of Chart specification, compare every plotted point and label with the referenced analytical result and metric catalog entry.
- For the analytics evidence of Chart specification, review keyboard access, contrast, non-color distinctions, text alternatives, small screens, and export rendering with representative fixtures.
Adoption assumptions
- The adopting product has authenticated identity, a versioned authorization policy, owned metric definitions, bounded telemetry, and a controlled path for change.
- Names and values in the example are fictional adoption fixtures, not universal defaults, production credentials, performance promises, or business targets.
- Referenced specifications constrain protocol, security, accessibility, or vendor behavior; the adopting team must confirm current applicability before promotion.
The executable-looking examples in this package are fixtures and acceptance contracts. Run the collection validator to check structure and metadata, then translate and execute the scenarios in the target repository before recording implementation evidence.
References
- Vega-Lite View Specification (applies as of 2026-09-12)
- W3C WAI, Complex Images tutorial (applies as of 2026-09-12)
- W3C Web Content Accessibility Guidelines 2.2