Specifies storage, interfaces, validation, access, freshness, monitoring, and failure behavior for chart specification, so adopters can represent a chart as validated, portable data and visual semantics that remain consistent with the metric and comparison...
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, implement the semantic contract through owned, typed boundaries 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: implement the semantic contract through owned, typed boundaries, 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 implemented Chart specification boundary enforces this rule: The agent emits a constrained chart schema, never executable JavaScript, HTML, template expressions, remote URLs, or renderer-specific escape hatches.
- The implemented Chart specification boundary enforces 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 implemented Chart specification boundary enforces 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 implemented Chart specification boundary enforces this rule: Primary and comparison series use consistent intervals, grains, units, and missing-value rules inherited from the resolved metric query.
- The implemented Chart specification boundary enforces this rule: Axes, legends, titles, annotations, and tooltips use registered display names and plain descriptions rather than internal identifiers.
- The implemented Chart specification boundary enforces this rule: Truncated axes, logarithmic scales, stacked totals, dual axes, smoothing, sampling, and normalization require explicit visible disclosure.
- The implemented Chart specification boundary enforces this rule: Every chart has a concise text summary and an accessible data table or long description containing essential values, relationships, and trends.
- The implemented Chart specification boundary enforces this rule: The renderer validates schema version, field references, row limits, color safety, and output size before producing the visual artifact.
Implementation guidance
- Store the versioned semantic object separately from database-specific compiled artifacts and presentation-specific documents.
- Validate at ingestion, registry, query, result, and rendering boundaries and keep one normalized representation through downstream steps.
- Roll out additively, compare old and new evidence over frozen fixtures, and keep a reversible migration until consumers adopt the new version.
- Instrument success, rejection, staleness, partial results, version conflicts, and repair without recording sensitive payloads.
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 implementation evidence of Chart specification, validate chart documents against the declared schema and reject code, external resources, undeclared fields, and excessive result sizes.
- For the implementation evidence of Chart specification, compare every plotted point and label with the referenced analytical result and metric catalog entry.
- For the implementation 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