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.

Extracting the spec

Copy the bundled spec.md to a target file:

npx @metabase/representations extract-spec --file ./spec.md

Omit --file to write spec.md into the current directory.

Extracting schemas

Copy the bundled schemas (preserving folder structure) into a target directory:

npx @metabase/representations extract-schema --folder ./schemas

Omit --folder to extract into 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 automatically by the Release to NPM GitHub Actions workflow on every push to main. The workflow compares the version in package.json against the version published on npm and publishes (with the latest dist-tag) if they differ.

To cut a release, bump version in package.json and merge to main.

The workflow requires an NPM_RELEASE_TOKEN secret with publish access to the @metabase npm org.