https://github.com/metabase/representations
https://github.com/metabase/representations
Last synced: 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/metabase/representations
- Owner: metabase
- License: other
- Created: 2026-03-27T19:22:25.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-02T19:58:04.000Z (2 months ago)
- Last Synced: 2026-04-04T05:44:19.944Z (2 months ago)
- Language: JavaScript
- Size: 364 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Metabase Representation Format
Metabase represents user-created content as a tree of YAML files. Each file represents one entity (a collection, card, dashboard, etc.). The format is designed to be **portable** across Metabase instances: numeric database IDs are replaced with human-readable names and entity IDs.
This repository contains the specification and examples for the Metabase Representation Format.
## Contents
- **[core-spec/v1/spec.md](core-spec/v1/spec.md)** — Full specification (v1.0.0) covering entity keys, folder structure, MBQL and native queries, parameters, and all entity types.
- **[core-spec/v1/schemas/](core-spec/v1/schemas/)** — YAML schemas (JSON Schema format) for each entity type.
- **[examples/v1/](examples/v1/)** — Complete examples using the Sample Database.
## Entity Types
| Entity | Description |
|--------|-------------|
| Collection | Folder-like container for organizing content |
| Card | Question, model, or metric — holds an MBQL or native query |
| Dashboard | Grid layout of cards with filter parameters and tabs |
| Segment | Saved filter definition scoped to a table |
| Measure | Saved aggregation definition scoped to a table |
| Snippet | Reusable SQL fragment for native queries |
| Transform | Materializes query or Python script results into a database table |
| TransformTag | Label for categorizing transforms (built-in or custom) |
| TransformJob | Scheduled job that executes tagged transforms |
| PythonLibrary | Shared Python source file available to Python transforms |
## Schema Validation
### CLI
Validate a folder of YAML files against the schemas:
```sh
npx @metabase/representations validate-schema --folder ./my-export
```
Omit `--folder` to validate the current directory.
### Programmatic
```js
import { validateSchema } from "@metabase/representations";
const { results, passed, failed } = validateSchema({
folder: "./my-export",
});
for (const result of results) {
if (result.status === "fail") {
console.log(result.file, result.errors);
}
}
```
## Publishing to NPM
Releases are published via the **Release to NPM** GitHub Actions workflow.
1. Go to **Actions > Release to NPM > Run workflow**.
2. Enter the version (e.g. `1.1.0`) and pick a dist-tag (`latest`, `next`, or `canary`).
3. Click **Run workflow**.
The workflow requires an `NPM_RELEASE_TOKEN` secret with publish access to the `@metabase` npm org.