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:

   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.