You have a Vega-Lite specification, but opening the JSON gives your colleague a page of braces. The specification needs a renderer and a place in an HTML document. Vega-Embed connects those pieces; your report supplies the title, explanation, and data the reader needs.
Use a small, explicit example before connecting a remote dataset. The sample compares three fictional routes: North has 14 stops, East has 9, and West has 17. The chart and its accompanying table should both say 40 stops in total.
Open the working example · Download the complete HTML
Put the data in the specification
A data.values array travels with the page. A data.url points somewhere else, so it creates a separate delivery dependency. For a short handoff, embed only the approved rows you intend the reader to receive.
const spec = {
$schema: "https://vega.github.io/schema/vega-lite/v6.json",
description: "Fictional route stops: North 14, East 9, West 17.",
width: "container", height: 220,
data: {values: [
{route: "North", stops: 14},
{route: "East", stops: 9},
{route: "West", stops: 17}
]},
mark: {type: "bar", tooltip: true},
encoding: {
x: {field: "route", type: "nominal", title: "Route"},
y: {field: "stops", type: "quantitative", title: "Stops"}
}
};
vegaEmbed("#chart", spec, {renderer: "svg", actions: false});
Create <div id="chart"></div> before running that code. Load Vega first, then Vega-Lite, then Vega-Embed, and finally your own script. The official embedding page shows the three libraries and their browser distributions.
Keep the schema and runtime versions compatible
The example uses Vega-Lite 6 with the corresponding Vega 6 and Vega-Embed 7 generation. Pin the exact releases used in your delivery file. A major-version URL can change beneath an archived report; an unversioned URL gives you even less control over what will load later.
The worked download embeds those library files and the route values inside its HTML. Its $schema address identifies the specification format; the example does not fetch the schema to draw the chart. There is no remote data source.
Preserve the answer outside the chart
Put “40 stops across three routes” in normal text. Add a table with the three route counts and a caption stating that the data is fictional. This lets a reader get the numbers without relying on hover, color, or a chart export menu.
For real data, write the period next to the finding and keep a reference to its source. An attractive bar does not tell the reader whether a count means planned stops, completed stops, or a forecast. Choose that definition before labeling the axis.
If your specification uses transformations, calculate a few resulting values separately. A summed field, a count of rows, and a count of distinct routes can all produce plausible bars while answering different questions. HTML chart preparation covers the surrounding page; Vega-Lite's specification controls this particular visualization.
Deliver a report, not a JSON fragment
Open the finished HTML and confirm the route labels, 14/9/17 values, 40-stop total, and narrow-screen layout. Keep the editable specification with the source material. The report's first screen should explain the comparison before the reader needs a tooltip.
A NOS page is a place to present that completed HTML reading copy with its explanation. Do not remove the table when you add the interactive chart: the reader still needs a clear, copyable record of the values.