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.
• CONTRIBUTING.md — How releases and alpha builds from a pull request are published.

Entity Types

Entity	Description
Collection	Folder-like container for organizing content
Card	Question, model, or metric — holds an MBQL or native query
Action	A parameterized native SQL write in a collection; implicit row actions on a model are deprecated
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
TransformTest	Test data for a transform's input tables and checks on its output
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.

Generating entity IDs

Print one or more 21-character NanoID entity IDs (one per line):

npx @metabase/representations generate-entity-id
npx @metabase/representations generate-entity-id --count 5

Generating UUIDs

Print one or more v4 UUIDs (one per line):

npx @metabase/representations generate-uuid
npx @metabase/representations generate-uuid --count 5

Programmatic

import {
  generateEntityId,
  generateUuid,
  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);
  }
}

const entityId = generateEntityId(); // "LZfXLFzPPR4NNrgjlWDxn"
const uuid = generateUuid(); // "1d4e9fdf-49ae-4fbe-ae27-05e7c6a5cfe8"