Loading Data and Images#
A Vega or Vega-Lite specification can carry its data inline or point to it with a URL. Inline data in data.values or datasets never touches the network or the disk and is never restricted. This page covers other configurations: How VlConvert resolves a data.url, which URLs and files it may read, and how the same rules apply to images.
Two converter settings control loading:
base_urlis the base for relative URLs. It defaults to the Vega datasets CDN, so thedata/cars.jsonshorthand used by the Vega editor and the Vega-Lite examples works without configuration.allowed_base_urlslists the URLs and directories a specification may read. It defaults to any HTTP or HTTPS URL and no local files.
How a Data URL Is Resolved#
VlConvert recognizes absolute filesystem paths before Vega resolves relative URLs against base_url:
URL in the specification |
Result with default settings |
|---|---|
|
Fetched with an HTTP GET request |
|
Joined to |
|
Local file, blocked unless allowed |
|
Local file, blocked unless allowed |
|
Local file, blocked unless allowed |
|
Fetched as |
|
Decoded inline, always allowed |
Absolute paths and file:// URLs do not use base_url. To read a local file, add its directory to allowed_base_urls. Every resolved HTTP URL or file path is checked against the allowlist. A request that fails the check raises an error whose message contains VLC_ACCESS_DENIED.
Allowlist Patterns#
Each entry in allowed_base_urls is one of these patterns:
Pattern |
Example |
Matches |
|---|---|---|
Scheme |
|
Any URL with that scheme |
URL prefix |
|
URLs that start with the prefix. A trailing |
Wildcard host |
|
The host and its subdomains, optionally limited to a path prefix |
Directory |
|
Files under that directory, after resolving symlinks and |
Everything |
|
Any URL or path, including the whole filesystem |
Prefix entries cannot contain credentials, a query string (?…),, or a fragment (#…). Directory entries must exist when the converter starts, and on Windows they can use drive letters such as C:\data\. An empty list blocks every HTTP or HTTPS URL and filesystem path. Inline data: URLs remain allowed.
The file: pattern allows any local file the process can read, including absolute paths without a file:// prefix. Use it only with trusted specifications. An allowlist containing only file: blocks HTTP and HTTPS access. Include http: and https: to allow those as well.
Load Local Files#
For an absolute path such as /srv/data/sales.csv, add /srv/data to allowed_base_urls. No change to base_url is needed. The file must exist on the machine running VlConvert, and the process must have permission to read it.
Use Relative Paths#
To use relative URLs instead, set base_url to the directory that holds the data and add that directory to allowed_base_urls. The following examples resolve data/sales.csv against the local example directory.
Create this layout, then run the examples from the example directory:
example/
├── chart.vl.json
└── data/
└── sales.csv
Save this specification:
chart.vl.json
{
"$schema": "https://vega.github.io/schema/vega-lite/v6.json",
"data": {"url": "data/sales.csv"},
"mark": "bar",
"encoding": {
"x": {"field": "category", "type": "nominal", "axis": {"labelAngle": 0}},
"y": {"field": "sales", "type": "quantitative"}
}
}
Save this data as data/sales.csv:
data/sales.csv
category,sales
A,28
B,55
C,43
D,91
E,81
from pathlib import Path
import vl_convert as vlc
example_dir = Path.cwd().resolve()
vlc.configure(
base_url=str(example_dir),
allowed_base_urls=[str(example_dir)],
)
spec = Path("chart.vl.json").read_text(encoding="utf-8")
png = vlc.vegalite_to_png(spec)
Path("chart.png").write_bytes(png)
base_url=False rejects relative URLs, and base_url=True restores the CDN default.
For production, use a stable absolute path such as /srv/charts. Keep the allowlist limited to the directory the chart needs.
HTTP Requests and Failures#
For remote resources, VlConvert makes GET requests to http and https URLs only. Each request has a 10-second connection timeout and a 30-second overall limit. This includes up to ten redirects, each checked against the allowlist.
The time limit applies to each attempt. Image fetches for SVG-based output retry transient server errors up to four times, so a failing image can take longer overall.
Vega parses data as JSON, CSV, TSV, or TopoJSON according to the file extension or the format property. See the Vega-Lite data documentation.
Use the Vega Example Datasets#
Vega and Vega-Lite examples reference their sample data with paths such as data/movies.json. With the default settings these work as they do in the Vega editor: the path is joined to base_url, which points at version 3.2.1 of the vega-datasets package on the jsDelivr CDN, and that CDN is covered by the default HTTPS allowlist. No configuration is needed.
The paths stop working when either setting changes:
If you narrow
allowed_base_urls, add the CDN prefixhttps://cdn.jsdelivr.net/npm/vega-datasets@v3.2.1/to the list.If you set
base_urlto a local directory,data/movies.jsonresolves under that directory instead. Either copy the datasets there or use absolute CDN URLs in the specification.If
base_urlis disabled, relative paths fail. Use absolute URLs.
To render the examples offline, download the vega-datasets package, for example with npm pack vega-datasets@3.2.1 or by cloning github.com/vega/vega-datasets, then set base_url to the directory that contains its data folder and add that directory to allowed_base_urls as shown above. To use a different dataset release, set base_url to its CDN URL, such as https://cdn.jsdelivr.net/npm/vega-datasets@3/.
Restrict Remote Data#
The default allows any HTTP or HTTPS host. For specifications you do not fully control, replace it with the prefixes or wildcard hosts of the services the application uses, and keep local directories out of the list unless they are needed. Security and Network Access shows the resulting configuration for each interface together with the other limits a public service needs.
Images#
Images follow the same rules as data. This covers Vega image marks, whose url can be a URL or a path, and <image> elements in SVG input. data: URLs are always allowed, and both HTTP images and local image files must match allowed_base_urls. A relative image path in an SVG input document resolves against a filesystem base_url and fails without one.
An SVG used as an image cannot pull in further images from files or hosts. Only data: references inside it are honored. To keep such images, inline them as data: URLs or flatten the SVG before conversion.
Which outputs load images follows the same pattern as data. PNG, JPEG, and PDF output, SVG input conversions, and SVG output with bundle load them during conversion. Plain SVG output keeps each image URL for the viewer to load. HTML usually leaves image loading to the browser, but the font processing described below evaluates the chart and can load its images during conversion.
Where images are loaded, a blocked image fails the conversion with a VLC_ACCESS_DENIED error. An image that is allowed but cannot be fetched, for example because the host returned an error, is logged as a warning and left blank, except with bundle, which fails because it must inline the image.
When Data Is Loaded#
Not every output fetches data. Compiling Vega-Lite to Vega and creating a Vega editor URL embed the specification as written. The data loads later under the browser’s or Vega editor’s rules rather than VlConvert’s. HTML generation also defers data loading unless Google Font discovery, an explicit Google Font request, or local font embedding makes VlConvert evaluate the chart to resolve fonts. In that case, VlConvert can load the data while generating the file, and the browser loads it again when the page opens. Rendered outputs, scenegraph output, and font inspection evaluate the chart and load its data during conversion.
Absolute-path handling applies when VlConvert loads resources. It does not make local paths portable in HTML or Vega Editor links. For those outputs, inline the data and images or use URLs the browser can access.
Configuration#
See Configuration for information on keeping these settings in a config file