Converting from Vega-Lite#

Use the Vega-Lite functions for charts authored in Vega-Lite. VlConvert compiles the specification to Vega with the bundled Vega-Lite library, then returns or renders the result.

Available outputs: compiled Vega JSON, SVG, PNG, JPEG, PDF, HTML, a Vega Editor URL, an evaluated scenegraph. SVG, HTML, and URL outputs are text. PNG, JPEG, and PDF outputs are bytes.

VlConvert bundles several Vega-Lite versions and uses the newest by default. See Supported Vega-Lite Versions to select another compiler. The setting does not change the input’s $schema field.

The examples below use the same input from Quick Start:

chart.vl.json
{
  "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
  "data": {
    "values": [
      {"category": "A", "value": 28},
      {"category": "B", "value": 55},
      {"category": "C", "value": 43},
      {"category": "D", "value": 91},
      {"category": "E", "value": 81}
    ]
  },
  "mark": "bar",
  "encoding": {
    "x": {"field": "category", "type": "nominal"},
    "y": {"field": "value", "type": "quantitative"}
  }
}

Send a request body to the endpoint for the output you need:

Output

Endpoint

Compiled Vega

POST /vegalite/vega

SVG

POST /vegalite/svg

PNG

POST /vegalite/png

JPEG

POST /vegalite/jpeg

PDF

POST /vegalite/pdf

HTML

POST /vegalite/html

Vega Editor URL

POST /vegalite/url

Scenegraph

POST /vegalite/scenegraph

Resolved fonts

POST /vegalite/fonts

For example, save this complete SVG request as request.json:

request.json
{
  "spec": {
    "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
    "data": {
      "values": [
        {
          "category": "A",
          "value": 28
        },
        {
          "category": "B",
          "value": 55
        },
        {
          "category": "C",
          "value": 43
        },
        {
          "category": "D",
          "value": 91
        },
        {
          "category": "E",
          "value": 81
        }
      ]
    },
    "mark": "bar",
    "encoding": {
      "x": {
        "field": "category",
        "type": "nominal"
      },
      "y": {
        "field": "value",
        "type": "quantitative"
      }
    }
  }
}
$ curl http://127.0.0.1:3000/vegalite/svg \
>   -H 'Content-Type: application/json' \
>   --data-binary @request.json \
>   --output chart.svg

The response body contains the output directly. See Server API for the other request fields and response content types.

Supported Vega-Lite Versions#

This VlConvert release accepts these major/minor versions, listed from oldest to newest. The newest is the default:

5.8, 5.14, 5.15, 5.16, 5.17, 5.20, 5.21, 6.1, 6.4

Each selects the bundled patch release for that major/minor version. A full version string such as 6.4.1 selects the same compiler as 6.4, not that exact patch release.

Set "vl_version": "6.4" in the request body. GET /info returns the server’s supported versions in vegalite_versions.

Related guides: Loading Data and Images for specifications that load data from URLs or files, Image Size and Quality Recommendations for size and resolution options, Themes and Number and Time Locales for appearance and formatting, Interactive HTML Output for interactive pages, and Evaluated Scenegraph Output and Font Introspection for the intermediate outputs.