[Tools](https://oods-foundry.com/tools) / viz_render # `viz_render` Render one data-bound chart from rows or a structured data operand. Generated from @oods/foundry 0.10.1 One of the 20 tools your assistant sees by default. Use it when creating chart output; use artifact_certify instead to grade a normalized chart or dashboard_render for multiple panels and KPIs. Returns Vega-Lite or ECharts specs, chart identities and requested SVG/accessibility output. pattern uses bundled data and forbids explicit data/encoding/presentation overrides. Otherwise use chartType plus encodings, omit chartType for recommendations, or supply structured intent. ECharts-primary families require their matching hierarchy/network/geo operand. brand/theme controls pixels; output.includeNormalizedSpec returns the IR required by artifact_certify. Temporal rendering uses UTC. Reference: TOOL-REFERENCE.md#viz_render; full schema: oods\://schemas/viz_render.input.json. ## Inputs | Name | Type | Required | Description | | - | - | - | - | | `theme` | `"light" \| "dark" \| "hc"` | no | CSS token theme for chart pixels, default light. See full schema for details. | | `brand` | `string` | no | CSS token brand for chart pixels. Omission resolves light/A. | | `opacity` | `number` | no | Optional constant mark opacity for the five Cartesian chart families. See full schema for details. | | `rows` | `object[]` | no | Inline data rows — the primary data path. Bounded: a few hundred rows is the sweet spot. Each row is a flat object mapping field name to value. | | `datasetRef` | `string` | no | Reference to a previously cached dataset (schemaRef-style TTL cache) to use instead of inline rows. Provide exactly one of 'rows' or 'datasetRef'. | | `hierarchy` | `object` | no | Hierarchy data for chartType 'treemap' or 'sunburst' (explicit-only) — used INSTEAD of rows/datasetRef + x/y encodings. See full schema for details. Variant fields: type, data. Read the full schema for each variant. | | `sankey` | `object` | no | Flow data for chartType 'sankey' (explicit-only) — used INSTEAD of rows/datasetRef + x/y encodings. See full schema for details. | | `chord` | `object` | no | Chord data for chartType 'chord' (explicit-only) — used INSTEAD of rows/datasetRef + x/y encodings. See full schema for details. | | `network` | `object` | no | Network data for chartType 'force_graph' (explicit-only) — used INSTEAD of rows/datasetRef + x/y encodings. See full schema for details. | | `geo` | `object` | no | Geo data for chartType 'choropleth', 'bubble_map', or 'flow_map' (explicit-only) — used INSTEAD of rows/datasetRef + x/y encodings. See full schema for details. | | `chartType` | `"bar" \| "line" \| "area" \| "scatter" \| "heatmap" \| "treemap" \| "sunburst" \| "sankey" \| "force_graph" \| "choropleth" \| "bubble_map" \| "flow_map" \| "chord"` | no | Chart type. See full schema for details. | | `encodings` | `object` | no | Channel -> field bindings. Required, with at least x and y, when chartType is supplied (explicit mode). | | `id` | `string` | no | Optional stable identifier for the produced spec. | | `name` | `string` | no | Optional human-friendly chart title. | | `description` | `string` | no | Optional override for the synthesized accessibility description. When omitted, a non-empty description is generated from the encodings. | | `strictFields` | `boolean` | no | Field/key-presence STRICT switch. See full schema for details. | | `a11yEquivalence` | `boolean` | no | A11y equivalence CERTIFY-AT-EMISSION switch. See full schema for details. | | `output` | `object` | no | Optional render output controls. Omitting this object preserves compact, Vega-Lite-only behavior. | | `intent` | `object` | no | STRUCTURED (typed, NOT free-text) visualization intent — the deterministic half of the NL→viz hand-off. See full schema for details. | | `pattern` | `"pattern:viz:bubble-distribution" \| "pattern:viz:correlation-matrix" \| "pattern:viz:correlation-scatter" \| "pattern:viz:detail-overview-bar" \| "pattern:viz:diverging-bar" \| "pattern:viz:drilldown-stacked-bar" \| "pattern:viz:facet-small-multiples-line" \| "pattern:viz:facet-target-band" \| "pattern:viz:focus-context-line" \| "pattern:viz:grouped-bar" \| "pattern:viz:histogram" \| "pattern:viz:layered-line-area" \| "pattern:viz:multi-series-line" \| "pattern:viz:running-total-area" \| "pattern:viz:simple-bar" \| "pattern:viz:sparkline-grid" \| "pattern:viz:stacked-100-bar" \| "pattern:viz:stacked-area-projection" \| "pattern:viz:stacked-bar" \| "pattern:viz:target-band-line" \| "pattern:viz:time-grid-heatmap" \| "pattern:viz:waterfall"` | no | Exact versioned pattern source identity. See full schema for details. | ## Outputs | Name | Type | Required | Description | | - | - | - | - | | `status` | `"ok" \| "error"` | yes | Whether rendering succeeded. | | `chartType` | `string` | no | Resolved registered chart type; omitted on error. | | `mode` | `"explicit" \| "suggest"` | no | Whether the chart type was supplied explicitly or chosen by the recommender. | | `spec` | `object` | no | Vega-Lite source with scoped OODS tokens, before the renderer's high-contrast quantized legend and output.width/height sizing adjustments. Use output.includeVegaSpec for the exact compiled Vega spec that reproduces the rendered chart. Scope changes alter chart content and pixel hashes. | | `echartsSpec` | `object` | no | Compiled ECharts option. Primary ECharts chart types include scoped OODS canvas, borders, labels and title chrome. Series palettes use the same scope; where no themed palette exists they retain the light palette. | | `normalizedSpec` | `object` | no | The intermediate NormalizedVizSpec IR. Present only when output.includeNormalizedSpec is true. | | `a11yDescription` | `string` | no | The non-empty accessibility description carried by the spec (always synthesized when not provided). | | `a11y` | `object` | no | Structured two-part text alternative (accessible data table + narrative summary) derived from the SAME data source the chart renders from. Present only when output.includeA11y is true (additive; default-off keeps the wire byte-identical). An agent reads this to verify/iterate its own chart without re-deriving the data. | | `suggestion` | `object` | no | Present in suggest mode: the recommender pick that drove the chart type, with the data-aware rationale and runner-up alternatives. | | `lowConfidence` | `boolean` | no | Suggest mode only: true when no pattern matched confidently — the chartType is a low-confidence fallback rather than a positive recommendation (the previously-silent bar default, now surfaced). | | `svg` | `string` | no | Server-rendered SVG bytes, present only for output.svg:true. ECharts allocator tokens are normalized before return; Vega-Lite retains its accessible graphics roles. | | `svgHash` | `string` | no | SHA-256 of the exact returned SVG bytes. At default intrinsic dimensions and light/A scope, cartesian svgHash equals artifact.certify determinism.renderHash for the same normalized spec. Scope and dimension changes alter the hash. | | `svgBytes` | `integer` | no | UTF-8 byte length of svg. | | `svgRef` | `string` | no | Temporary pipeline reference caching exactly the svg string, with the same lifetime as specRef. | | `render` | `object` | no | Actual SVG dimensions, primary engine and rendered scope. | | `specRef` | `string` | no | Temporary reference to the produced spec for pipeline reuse (mirrors the retired chart scaffold schemaRef). | | `specRefCreatedAt` | `string` | no | ISO timestamp when the specRef was created. | | `specRefExpiresAt` | `string` | no | ISO timestamp when the specRef expires. | | `contentHash` | `string` | no | Deterministic SHA-256 (hex) over the canonicalized primary payload (the Vega-Lite spec, or the JSON-projected ECharts option for ECharts-primary types) — the content IDENTITY of exactly what specRef caches. Unlike specRef (a random, expiring cache handle), contentHash is stable across calls: the same input yields the same hash. Default-on; omitted only on error outputs. | | `tokenCssRef` | `string` | no | Content-addressed identity of the active token CSS when compact mode is enabled: tokens.build#sha256:\. Use tokens.build to obtain the full CSS. | | `output` | `object` | no | Echoes the normalized output controls used by the renderer. | | `errors` | `issue[]` | no | Fatal errors (present and non-empty when status is 'error'). | | `warnings` | `issue[]` | yes | Non-fatal issues encountered during rendering. | | `meta` | `object` | no | | | `vegaSpec` | `object` | no | The exact Vega spec parsed by the renderer after legend and sizing adjustments. Present for Vega charts only when output.includeVegaSpec is true. Rendering with the bundled Vega version reproduces the SVG apart from its accessibility and stable-ID post-processing. | ## A real call Recorded by this site's `harbor` run, step `chart`, with the published OODS Foundry 0.10.1. Its input: ``` { "chartType": "bar", "brand": "Harbor", "theme": "light", "rows": [ { "warehouse": "Lakeside Distribution", "pallets": 640 }, { "warehouse": "North Yard", "pallets": 760 }, { "warehouse": "Harbor Cold Store", "pallets": 2400 } ], "encodings": { "x": { "field": "warehouse", "type": "nominal" }, "y": { "field": "pallets", "type": "quantitative" } }, "output": { "includeNormalizedSpec": true, "includeA11y": true } } ``` Its result, first lines: ``` { "status": "ok", "chartType": "bar", "mode": "explicit", "spec": { "$schema": "https://vega.github.io/schema/vega-lite/v6.json", "title": "Bar chart", "description": "Bar chart of pallets by warehouse.", "data": { "values": [ { "warehouse": "Lakeside Distribution", "pallets": 640 }, { "warehouse": "North Yard", "pallets": 760 }, { "warehouse": "Harbor Cold Store", "pallets": 2400 } ] }, "autosize": { "type": "fit-y", "contains": "padding" }, "config": { "background": "#FFFFFF", "font": "'DM Sans', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif", "title": { "color": "#070B0B", "font": "'DM Sans', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif", "fontSize": 24, "fontWeight": 600, "anchor": "start" }, "axis": { "titleColor": "#070B0B", "titleFont": "'DM Sans', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif", "labelColor": "#4C5455", "labelFont": "'DM Sans', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif", "gridColor": "#E1E6E7", "domainColor": "#CFD6D7", "tickColor": "#CFD6D7" }, "axisX": { "grid": false }, "axisY": { "grid": true, "tickCount": { "expr": "min(5, ceil(height / 40))" } }, "legend": { "titleColor": "#070B0B", "titleFont": "'DM Sans', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif", "labelColor": "#4C5455", ``` [The whole call, 7 KB of JSON](https://oods-foundry.com/tools/viz-render/call.json)