--json-schema（ジェイソンスキーマ）

print mode で Claude の出力を別ツールに渡したいが、テキストを後から取り出すのが辛い段階の人向け

Claudeにテキスト処理を任せたあと、その結果を別のプログラムに食わせたい場面はわりとあります。商品レビュー記事から商品名と価格を抜きたい、メールの本文からタイトルと締切を抜きたい、社内ドキュメントから章タイトル一覧を作りたい、みたいな話です。

普通に claude -p "...抜いて" と叩くとClaudeは人間に読ませる形のテキストで返してきます。これを後段のスクリプトで切り分けるのが地味につらい。--json-schema はここを解決する起動時の指定で、「こういう形のJSONで返して」と型の設計図を渡すと、Claudeがそれに合った構造化JSONを最後に1個だけ吐いてくれます。

噛み砕くと、Claudeへの「納品書のテンプレ」を先に渡してる

Claudeに作業を頼むとき、口頭で「商品名と価格を出して」と言うのと、「この空欄を埋めて返してください」と紙の様式を渡すのでは、後者のほうが受け取り側はラクです。

--json-schema は後者の「紙の様式」をJSONで渡す指示です。JSON Schema（ジェイソンスキーマ）という業界共通の書式で「項目はnameとpriceとrating、それぞれの型は文字列・数値・整数」と設計図を渡すと、Claudeはその様式に合わせた答えしか返してこなくなります。

納品物の形が事前に決まってる、これが効きます。

大事な前提：この指定は print mode 専用

公式ドキュメントには「(print mode only)」と明記されています。print modeというのは claude -p "..." の形でClaudeを叩く使い方で、対話画面を開かずに「質問を渡す→答えを1回返す→終了」と単発実行するモードです。

普段 claude とだけ叩いて開く対話画面では --json-schema を付けても効きません。「スクリプトから呼んで結果を受け取る用」と覚えるとズレません。

「商品レビュー記事から商品名・価格・5段階評価を抜く」を例に、実際の手順を見る

料理ブログを運営していて、自分が書いたキッチン家電のレビュー記事から「商品名・価格・5段階評価」を一覧表にしたい、という場面を想定します。最終的にはGoogleスプレッドシートに貼り付けて、家電比較表として使いたい。

ステップ1: レビュー本文を1ファイルに置く

まずは元になるレビュー記事を review.txt として保存します。中身はこんな感じです。

バルミューダのトースター「The Toaster Pro」を3ヶ月使った感想を書きます。
価格は税込35,200円。正直、普通のトースターの3倍以上します。
ただ、パンの焼き上がりは本当に別物で、特にクロワッサンの再現性は驚きでした。
総合評価は5段階で4。値段がネックですが、パン好きには本気で勧められます。

ステップ2: JSON Schemaを設計する

欲しい形を先に決めます。「商品名（name）」「税込価格（price）」「5段階評価（rating）」の3項目です。JSON Schemaで書くとこうなります。

{
  "type": "object",
  "properties": {
    "name":   { "type": "string" },
    "price":  { "type": "number" },
    "rating": { "type": "integer", "minimum": 1, "maximum": 5 }
  },
  "required": ["name", "price", "rating"]
}

3行覚えとけば十分です。type: "object" でJSONオブジェクト、properties で項目名と型、required で必須項目。minimum と maximum も指定しておくと「rating: 7」みたいな範囲外の値が返ってくる事故を減らせます。

ステップ3: コマンドを組み立てる

レビュー本文をClaudeに渡しつつ、スキーマで型を縛ります。本文の渡し方はパイプ | を使うのが手軽です。

$ cat review.txt | claude -p \
  --output-format json \
  --json-schema '{"type":"object","properties":{"name":{"type":"string"},"price":{"type":"number"},"rating":{"type":"integer","minimum":1,"maximum":5}},"required":["name","price","rating"]}' \
  "このレビュー本文から商品名(name)・税込価格(price)・5段階評価(rating)を抜き出して"

スキーマはシングルクオート '...' で囲うのが安全です。中にダブルクオートを書く都合上、外側をダブルにするとエスケープ地獄になります。

ステップ4: 返ってくるJSONを受け取る

うまく行けば最後にこんな形のJSONが標準出力に出ます。

{
  "name": "バルミューダ The Toaster Pro",
  "price": 35200,
  "rating": 4
}

ここで初心者がやりがちな勘違いがあります。「途中の考えてる過程もJSONで返ってくる」と思い込むケースです。--json-schema は「agent completes its workflow（作業が全部終わった後）」のタイミングで最終結果として1個だけ吐く仕様で、途中の思考やツール呼び出しはJSONになりません。途中経過も含めて全部JSONで欲しい場合は別途 --output-format stream-json 等の合わせ技が要ります。

ステップ5: スプレッドシートに流し込む

出力を jq や Python で1行のCSVに変換して、Googleスプレッドシートに貼り付ければ完成です。10記事分回せば10行の比較表ができます。

$ cat review.txt | claude -p \
  --output-format json \
  --json-schema '...上と同じ...' \
  "..." \
  | jq -r '[.name, .price, .rating] | @csv'

"バルミューダ The Toaster Pro",35200,4

ステップ6: バッチに展開する

ターミナルの for ループで review-*.txt を全部舐めれば、10記事でも100記事でも回せます。これがprint mode専用である理由でもあります。「人が画面を見ている前提のClaude」ではなく、「スクリプトに組み込んで自動で回すClaude」のための機能です。

つまり --json-schema は何をしてくれるのか

• やってくれる: 最終出力の形を JSON Schema で固定する。後段のスクリプトが response.name response.price で素直に値を取れる状態にする
• やってくれる: minimum / maximum の範囲制約や、required の必須項目を守った答えを返す。「ratingが7」みたいな明らかな逸脱を防ぐ
• やってくれない: 途中の思考やツール実行ログをJSONで返すこと。あくまで「最後の納品物」だけ
• やってくれない: 対話画面での型固定。print mode 専用なので、普段の claude セッションでは効かない
• 意味が薄い場面: 出力を人間が直接読むだけの用途。記事執筆、相談、コードレビュー画面表示などは、JSON化する意味がない

使いどころ3シナリオ（具体題材で再現）

シナリオ1: 商品レビュー記事10本から比較表を作る

料理ブログの過去レビュー10本を review-01.txt から review-10.txt まで並べて、上で書いたコマンドを for ループで回します。10回叩いて10個のJSONを受け取り、jq でCSV化してGoogleスプレッドシートに貼ると、商品名・価格・評価が並んだ表が一発で完成します。テキストで「商品名は〇〇です。価格は△△円です」みたいに返してきたものを正規表現で抜き出す手間がゼロになる。地味ですがこれが効きます。

シナリオ2: 議事録から「決定事項」と「次回までのタスク」を抜く

会議の文字起こしが meeting.txt に保存されている前提で、スキーマを {"decisions": ["..."], "todos": [{"who": "...", "what": "...", "due": "..."}]} のような形にして渡します。Claudeは議事録全体を読んだうえで決定事項を文字列の配列に、TODOを担当者・内容・期限の3項目で抜き出して返してきます。これをそのままNotionのデータベースに流し込めば、議事録から自動でタスク管理に変換できる。手作業で「ここがタスクで、担当は誰で…」を読み直す作業が消えます。

シナリオ3: 求人ページのHTMLから募集要項だけ抜く

転職活動で気になる求人を10社分集めたいとき。各社の求人ページHTMLをローカルに保存して、スキーマで {"company": "...", "position": "...", "salary_min": 0, "salary_max": 0, "location": "...", "remote_ok": false} と指定して投げれば、レイアウトがバラバラなページからでも同じ形で抜けます。remote_ok は boolean なので、後段で「リモート可だけ抽出」もスプレッドシート関数1個でできる。テキストで「リモート勤務可能と書いてあります」と返されるよりずっと扱いやすいです。

初心者が踏みやすい落とし穴

• 対話画面で叩いて効かないと焦る。print mode専用なので、普段の claude セッションで /json-schema 的な感覚で使おうとしても効きません。claude -p から始める使い方に切り替える
• スキーマをターミナルでうまく渡せない。中にダブルクオートが入る都合上、外側をダブルで囲うとエスケープ地獄になります。シングルクオート '...' で囲うのが定石。長くなるならファイルに保存して --json-schema "$(cat schema.json)" も手
• 途中の思考プロセスもJSONで返ると思い込む。返るのは「workflow完了後の最終出力1個」だけです。途中経過も欲しい場合は --output-format stream-json や --include-partial-messages との組み合わせを検討する
• スキーマに合わない出力が返ったときの挙動を本記事で断言しない。公式 cli-reference は「validated JSON output matching a JSON Schema」とだけ書いており、validate fail 時の exit code や再試行の細部は /en/agent-sdk/structured-outputs のページに集約されています。本番運用する前に必ず読む
• スキーマが緩すぎて欲しい型が出ない。{"type": "object"} だけだと中身は自由形式になります。properties と required を両方指定し、数値項目には minimum maximum、文字列項目には enum（候補リスト）も使うと安定します
• --output-format を指定し忘れる。--json-schema だけ書いて --output-format を省くと、表示は人間向けテキストのままになるケースがあります。print mode で構造化結果が欲しい場合は --output-format json をセットで指定するのが安全
• print mode で他の起動時指定と混ぜたときの優先順位を読まずに使う。--max-turns --max-budget-usd 等と組み合わせると「途中で止まって最終JSONが出ない」ことがあり得ます。バッチを本番で回す前に必ず1件で動作確認する

書き方

claude -p --json-schema '<JSON Schema文字列>' "<質問>"

やってみるとこうなる

入力

cat review.txt | claude -p --output-format json --json-schema '{"type":"object","properties":{"name":{"type":"string"},"price":{"type":"number"},"rating":{"type":"integer","minimum":1,"maximum":5}},"required":["name","price","rating"]}' "このレビュー本文から商品名(name)・税込価格(price)・5段階評価(rating)を抜き出して"

出力例

{
  "name": "バルミューダ The Toaster Pro",
  "price": 35200,
  "rating": 4
}

関連項目

• /print（準備中）
• --output-format（アウトプットフォーマット）
• --input-format（インプットフォーマット）
• --verbose（ヴァーボース）
• --include-partial-messages（インクルードパーシャルメッセージズ）

公式ドキュメント

https://code.claude.com/docs/en/cli-reference