# Notion Schema Dump

> Generate a canonical SCHEMA-REFERENCE.md from a live Notion workspace. Use before authoring any filter, formula, view, or rollup — schema-first rule.

- Skill: `chiragg-ds/notion-schema-dump` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add chiragg-ds/notion-schema-dump`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chiragg-ds/notion-schema-dump/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: chiragg-ds (https://skillmd.com/u/chiragg-ds)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chiragg-ds/notion-schema-dump

---


# notion-schema-dump

Query each Notion database via the API and produce:
- `SCHEMA-REFERENCE.md` — human-readable table per DB (property name, type, select options, formula expression, relation targets, rollup signatures)
- `schema-reference.json` — machine-readable companion

This is the **single source of truth** for property names and select option values when authoring filters, formulas, views, or rollups.

## Why it matters

Notion property names are case-sensitive. Select option values must match exactly. Filters/formulas authored from memory or stale CSVs silently drift from live schema and break. Always regenerate this file before touching anything that references DB properties.

## Prerequisites

- `NOTION_API_KEY` env var
- A dict of `{db_name: db_id}` for the DBs you want to dump (or an `ids.json` from a prior `notion-provision` run)

## Steps

1. Find the DB IDs. If `ids.json` exists in the project, use that. Otherwise ask the user.
2. Run:
   ```python
   from notion_os_toolkit import auth, client, schema_dump
   from pathlib import Path
   nc = client.NotionClient(auth.load_token())
   db_ids = {"Projects": "...", "Tasks": "...", ...}
   schema_dump.dump(nc, db_ids, out_dir=Path("./"), brand_name="My Studio")
   ```
3. The two output files will appear in `out_dir`. Show the user the first few rows of `SCHEMA-REFERENCE.md` to confirm.

## Input/Output contract

**Input:** `db_ids` dict (or `ids.json` file path), output directory
**Output:** `SCHEMA-REFERENCE.md` + `schema-reference.json` written to `out_dir`

## When to invoke

- **Always before authoring any new filter / formula / view spec.**
- After any schema change (added property, renamed select option, etc.).
- When debugging "filter doesn't match anything" — usually a property-name typo.

## Reference

- `scripts/run.py` — driver
- Notion limit reminder: formula properties cannot reference other formula properties in date comparisons. Inline the underlying date column instead.