---
url: /mosaic/spec.md
---
# Mosaic Declarative Specifications

The `mosaic-spec` package enables declarative specification of Mosaic applications as JSON or YAML files. The package provides a specification parser, as well as generators to create either running applications or JavaScript code.

For example, below is an example of a declarative specification, in either YAML or equivalent JSON, for a simple line chart. The JavaScript and Python tabs show equivalent code that builds the same specification using the [`vgplot`](/vgplot/) API in each language.

```py \[Python]
import vgplot as vg

aapl = vg.parquet("data/stocks.parquet", where="Symbol = 'AAPL'")

view = vg.plot(
    vg.line_y(aapl, x="Date", y="Close"),
    vg.width(680),
    vg.height(200),
)

```

Using a declarative specification, we can describe an application in a standard file format, enabling portability across platforms. The same spec can be authored as YAML/JSON or built programmatically with the `vgplot` API in either JavaScript or Python (see the [Python API](/vgplot/?lang=python)). For example, the [Mosaic Jupyter widget](/jupyter/) uses this format to pass visualization and dashboard definitions from Python to the browser.

::: tip
The [TypeScript types in the `@uwdata/mosaic-spec` package](https://github.com/uwdata/mosaic/tree/main/packages/vgplot/spec/src/spec) provide comprehensive documentation of Mosaic declarative specifications.
:::

## Specification Format

Here is a slightly more complicated example, in which a dynamic `Param` value is added to the data before visualizing it.

```py \[Python]
import vgplot as vg

walk = vg.parquet("data/random-walk.parquet")

point = vg.param(0)

view = vg.vconcat(
    vg.slider(label="Bias", bind=point, min=0, max=1000, step=1),
    vg.plot(
        vg.area_y(walk, x="t", y=vg.sql("v + $point"), fill="steelblue"),
        vg.width(680),
        vg.height(200),
    ),
)

```

The example above includes descriptive metadata, `data` and `params` definitions, and nested components: an input `slider` and `plot` are positioned using a `vconcat` layout. The `plot` uses a SQL expression that includes a `Param` reference (`$point`) to define a dynamic `y` encoding channel.

A declarative specification may include top-level definitions for:

* `meta`: Metadata such as a title and description.
* `config`: Configuration settings, such as database extensions to load.
* `data`: Dataset definitions, such as files, queries, or inline data.
* `params`: Param & Selection definitions. All later Param references use a `$` prefix.
* `plotDefaults`: Default plot attributes to apply to all plot instances.

The rest of the spec consists of component definitions supported by the [`vgplot`](/vgplot/) API, including plots, inputs, and layout components.

For more, see the [Specification Format Reference](/api/spec/format).

## Parser & Generators Format

The `parseSpec()` method parses a specification in JSON format into an *abstract syntax tree* (AST): a structured representation of the specification content that is more convenient to analyze and manipulate.

Given a parsed AST, the generator method `astToDOM()` instantiates a running web application, returning Mosaic-backed Document Object Model (DOM) elements that can be added to a web page.

Meanwhile, the `astToESM()` method instead generates JavaScript code, in the form of an ECMAScript Module (ESM), that uses the `vgplot` API. The JavaScript code listed in the examples above was generated using this method, and `astToPython()` similarly generates equivalent Python code for the [`vgplot` Python API](/vgplot/?lang=python).

For more, see the [Specification Parser & Generators Reference](/api/spec/parser-generators).