第3章 Notionのデータモデルと基本構造

Notion API を使いこなすために最も重要な「データ構造」の基礎概念を解説します。ページ、データベース、ブロック、プロパティの関係を整理し、JSON レスポンスの読み解き方を学びます。

Notion の基本オブジェクト階層

Notion のコンテンツは、すべて「ブロック」と呼ばれる積み木のような単位で構成されています。全体の関係は以下の階層構造になっています。

Workspace（ワークスペース）
 ├── Database（データベース：構造化された表やリスト）
 │    └── Page（ページ：データベースの各行・レコード）
 │         └── Block（ブロック：見出し、本文段落、箇条書きなど）
 └── Page（単体の独立ページ）
      └── Block（ブロック）
           └── Child Blocks（子ブロック）

重要な点は、「データベースの各レコード（行）も、実体は 1 つの独立したページである」 という点です。行をクリックすると詳細ページが開く Notion の特徴が、そのまま API のデータ構造にも反映されています。

ブロック（Block）の仕組み

Notion のドキュメント本文は、1 行 1 行が独立した ブロック として管理されます。段落（paragraph）、見出し（heading_1, heading_2, heading_3）、チェックボックス（to_do）、箇条書き（bulleted_list_item）、コード（code）など、多彩なタイプが存在します。

ブロックは親子関係（入れ子構造）を持つことができます。たとえば、トグルリストや箇条書きのインデント行は、親ブロックの children として子ブロックがぶら下がります。

ブロックの JSON 表現例（段落ブロック）

{
  "object": "block",
  "id": "c1a2b3c4-...",
  "type": "paragraph",
  "paragraph": {
    "rich_text": [
      {
        "type": "text",
        "text": {
          "content": "こんにちは、Notion API！"
        },
        "plain_text": "こんにちは、Notion API！"
      }
    ]
  }
}

リッチテキストオブジェクト（Rich Text Object）

Notion のテキスト情報は、単純な文字列ではなく Rich Text Object の配列として表現されます。文章の一部分だけを太字にしたり、リンクを設定したり、文字色を変えたりできるのは、この構造のおかげです。

1 つのリッチテキスト要素には、主に以下のキーが含まれます：

type: 通常は "text"（メンションや数式の場合は "mention", "equation"）
text.content: 表示されるテキスト本文
text.link: リンク先 URL（設定されている場合）
annotations: 文字装飾（bold, italic, strikethrough, underline, code, color）
plain_text: 装飾を除去したプレーンテキスト

Python でテキストを抽出するときは、item["plain_text"] を参照すると装飾を気にせず文字列を取得できます。

データベースのプロパティ（Properties）

データベースの各列（属性）を プロパティ と呼びます。プロパティには厳密な型があり、型によって JSON の書き方が異なります。

プロパティ型	説明	JSON 値の指定方法の例
`title`	レコードの名前（1つのDBに必須で1列のみ）	`{"title": [{"text": {"content": "タイトル"}}]}`
`rich_text`	複数行や装飾が可能なテキスト列	`{"rich_text": [{"text": {"content": "メモ"}}]}`
`number`	数値（整数・小数）	`{"number": 42}`
`select`	単一選択ドロップダウン	`{"select": {"name": "進行中"}}`
`multi_select`	複数選択タグ	`{"multi_select": [{"name": "Python"}, {"name": "API"}]}`
`date`	日付（開始日・終了日・時刻）	`{"date": {"start": "2026-10-03"}}`
`checkbox`	チェックボックス（True/False）	`{"checkbox": true}`
`status`	ステータス列（Not started, In progress等）	`{"status": {"name": "完了"}}`
`url`	Web サイトのリンク	`{"url": "https://example.com"}`

データの取得と更新のルール

プロパティの値を更新する場合、指定するキー名は Notion 上の プロパティ名 または プロパティID と一致している必要があります。たとえば列名が「担当者」であれば、キー名にも "担当者" と指定します。

また、title プロパティは各データベースに必ず 1 列だけ存在し、行を識別するメインの見出しとして機能します。