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 — Full specification (v1.0.0) covering entity keys, folder structure, MBQL and native queries, parameters, and all entity types.
• core-spec/v1/schemas/ — YAML schemas (JSON Schema format) for each entity type.
• 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:

npx @metabase/representations validate-schema --folder ./my-export

Omit --folder to validate the current directory.

Programmatic

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.