Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(vega): document that specs are programs, with the untrusted-spec wiring (#5530)

Baraa Hamodi2bf24da207bb
diff --git a/packages/vega/README.md b/packages/vega/README.md
index f8c488ec51..9010a460cf 100644
--- a/packages/vega/README.md
+++ b/packages/vega/README.md
@@ -156,6 +156,43 @@ To update data dynamically after render, use `onReady` to get the live View and
/>
```
+### Untrusted specs
+
+A Vega/Vega-Lite spec is a program, not just data: Vega evaluates the
+expression strings inside it (signals, event streams, encodings, filters)
+and, by default, compiles them to JavaScript with the Function constructor.
+A spec's `data` entries can also name URLs — including signal-built dynamic
+ones — that the default loader will fetch with the page's credentials.
+
+`<VegaChart>` renders the spec you give it with Vega's defaults, so those
+defaults define the trust boundary: **only pass specs you author or
+review.** If specs come from users, stored documents, or model output, wire
+the safe evaluation mode through the existing pass-through options — Vega's
+own guidance for untrusted specs:
+
+```tsx
+import {expressionInterpreter} from 'vega-interpreter';
+import {loader} from 'vega';
+
+<VegaChart
+ spec={untrustedSpec}
+ // Retain the expression AST and evaluate it interpreted (no Function
+ // constructor). Slower, and a small subset of expressions is unsupported —
+ // see the vega-interpreter README.
+ parseOptions={{ast: true}}
+ viewOptions={{
+ expr: expressionInterpreter,
+ // Restrict (or disable) what a spec may load. `mode: 'file'` with no
+ // baseURL rejects everything; supply your own loader to allowlist hosts.
+ loader: loader({mode: 'file'}),
+ }}
+/>;
+```
+
+`vega-interpreter` is a separate package (`npm install vega-interpreter`);
+pair it with a `Content-Security-Policy` that omits `'unsafe-eval'` so the
+boundary is enforced by the platform, not only by configuration.
+
### `parseSchema(schema)` (exported utility)
Parses and validates a Vega `$schema` URL. Returns:
diff --git a/packages/vega/src/types.ts b/packages/vega/src/types.ts
index 95ab8a6775..40023bc879 100644
--- a/packages/vega/src/types.ts
+++ b/packages/vega/src/types.ts
@@ -12,9 +12,19 @@
import type React from 'react';
import type {Spec as VegaSpec, Config, View, ViewOptions} from 'vega';
import type {LoggerInterface} from 'vega-util';
-import type {TopLevelSpec as VegaLiteSpec, Config as VegaLiteConfig} from 'vega-lite';
+import type {
+ TopLevelSpec as VegaLiteSpec,
+ Config as VegaLiteConfig,
+} from 'vega-lite';
-export type {VegaSpec, VegaLiteSpec, Config, View, ViewOptions, LoggerInterface};
+export type {
+ VegaSpec,
+ VegaLiteSpec,
+ Config,
+ View,
+ ViewOptions,
+ LoggerInterface,
+};
/**
* Options for the Vega-Lite `compile()` function.
@@ -58,8 +68,12 @@ export type AnySpec = (VegaSpec | VegaLiteSpec) & {$schema: string};
export interface ParseOptions {
/**
* When `true`, the parser retains the abstract syntax tree (AST) of
- * Vega expressions in the runtime. Useful for introspection and tooling.
- * Defaults to `false`.
+ * Vega expressions in the runtime instead of compiling them with the
+ * Function constructor. Pair it with `viewOptions.expr` set to
+ * `vega-interpreter`'s evaluator to run spec expressions interpreted —
+ * the required configuration for specs you didn't author (see
+ * "Untrusted specs" in the README). Also useful for introspection and
+ * tooling. Defaults to `false`.
*/
ast?: boolean;
}
@@ -118,8 +132,18 @@ export interface VegaChartProps extends Omit<
* - `vega-lite` -> compiled to Vega via `vega-lite`'s `compile()`, then rendered
* - `vega` -> rendered directly without compilation
*
+ * **A spec is a program, not just data.** Vega evaluates the expression
+ * strings inside a spec (signals, event streams, encodings, filters) and,
+ * by default, compiles them with the Function constructor; a spec's data
+ * sources can also name URLs the default loader will fetch, including
+ * signal-built ones. Only render specs you author or review. For specs
+ * from users, documents, or model output, wire the interpreter and a
+ * restricted loader — see "Untrusted specs" in the README — and treat that
+ * configuration as required, not optional.
+ *
* @see https://vega.github.io/vega/docs/specification/
* @see https://vega.github.io/vega-lite/docs/spec.html
+ * @see https://vega.github.io/vega/usage/interpreter/
*/
spec: AnySpec;
/**