flint-chart-author

flint-chart：チャート仕様の作成と利用

作成するもの（および作成しないもの）

出力するのは仕様、つまりChartAssemblyInputのchart_specとsemantic_typesです。データ列は名前で参照します。ホストは生成された入力をassembleVegaLite、assembleECharts、またはassembleChartjsに渡し、バックエンド仕様を取得します。

作成するのは入力仕様であり、出力仕様ではありません。 特に、次の点に注意してください。

• chart_spec（チャートの種類、チャンネルからフィールドへのマッピング、プロパティ）とsemantic_types（フィールドからセマンティック型への対応）を出力してください。
• ユーザーが動作（ハイライト、凡例の切り替え、パンとズーム、ブラシ操作）を求めた場合、インタラクティブなチャートを求めた場合、またはセッションの目標がデータの探索である場合は、interaction_specを追加してください。 プリセットは名前で指定してください。「Interactions」を参照し、意図が指定されている場合、名前のないインタラクティブなチャートの場合、または組み合わせを使う場合は、flint-interaction-authorスキルを読み込んでください。
• 列は名前で参照してください。 data自体をどのようにバインドするかは、状況によって異なります。URL、ホスト側の変数、または埋め込み行を使用できます（「How data gets bound」を参照）。小さなテーブルなら埋め込みで問題ありませんが、大きなデータセットを手作業で再シリアライズしないでください。切り捨てや気づかないうちの値の破損を招くおそれがあり、トークンも浪費します。
• Flintに渡す前にデータを変換してください。 必要なチャートに集計、フィルタリング、結合、ピボット、派生列の作成、またはFlintの組み込み静的系列の折りたたみを超えるロング形式とワイド形式の変換が必要な場合は、先にコーディング、ノートブック、SQL、またはデータのツールを使ってください。その後、変換後のテーブルを使ってFlintの仕様を作成します。
• 必要な場合に限り、Flintの後でスタイルを調整してください。 構造はFlintで作成します。参照線、注釈、網掛け帯など、Flintで表現できない表示上の調整には、Vega-Liteのエスケープハッチを使ってください。「Post-Flint style customization」を参照してください。編集したVega-Lite JSONをrender_chartに渡し直してはいけません。

ユーザーが仕様以上のものを求めている場合

まず、ユーザーがどのワークフローを求めているか判断してください。

• 仕様の作成のみ： ChartAssemblyInput、またはその semantic_types と chart_spec の各要素を返します。求められていない限り、 パッケージをインストールしたり、レンダラーのコードを書いたりしないでください。
• MCP でのチャート出力： Flint MCP ツールを利用できる場合、ユーザーがチャートの表示を求めたときは、デフォルトで validate_chart の後に show を呼び出します。 validate_chart は仕様を検証し、描画せずにレポートを返します。仕様内で指摘された点を修正してから、 仕様全体を使って show({ "chart": … }) を一度呼び出すと、カスタマイズパネルを備えた、 インタラクティブでライブレンダリングされるカードが開きます。サーバーは呼び出し間で何も保持しないため、 会話内の仕様がチャートそのものです。ホストが App UI に対応していない場合、またはユーザーが 静止画像を明示的に希望した場合に限り、render_chart（PNG/SVG）を使用します。ユーザーが バックエンドネイティブの JSON を求めている場合は compile_chart を、対応するチャートの一覧が必要な場合は list_chart_types を使用します。
• 必ず、ユーザーがチャートを特定の状態で開くよう求めている場合は、入力とともに validate_chart と show に updates を渡します。対象となるのは、目立たせる行、マーク上の注記、 枠で囲む範囲などです。これは ChartUpdate レイヤーのリストであり、動作ではなく状態を表します。 形状については flint://interaction-skill の「チャートを更新する」を参照してください。後のターンで チャートを変更する場合は、仕様または updates を変更して、再度 show を呼び出します。 新しいカードに変更が表示され、以前のカードはそのまま残ります。カードのパネルで閲覧者が行った編集は そのカード上に保持されます。カードのコンテキストには、それらを保持する chart_spec が含まれるため、 ユーザーが別のものを求めていない限り、それを渡してください。
• 必ず、ユーザーがチャートの数値を見たい場合は show に view: "table" を渡します。 カードはチャートに描画される行のテーブルを表示して開き、閲覧者はチャートに切り替えられます。 ユーザーがレコードの一覧を求めていて、チャートが不要な場合は、代わりに chartType: "Table" を使用します。
• プロジェクトへの統合は、ユーザーがコードを求めた場合のみ： Flint をアプリ、ノートブック、 スクリプト、またはエージェント型製品に追加し、ライブラリをインストール／インポートして、コード内で アセンブラーを呼び出します。同じ ChartAssemblyInput の契約を維持し、ホストにバックエンドの結果を レンダリングさせます。

MCP クライアントでは、サーバーを npx で実行できます。

npx -y flint-chart-mcp

JavaScript または TypeScript プロジェクトでは、まず Flint をインストールし、レンダリングする バックエンドに必要なレンダラーピア依存関係のみを追加します。

npm install flint-chart
npm install vega vega-lite vega-embed  # browser Vega-Lite rendering
npm install echarts                    # ECharts rendering
npm install chart.js                   # Chart.js rendering

次に、指定されたバックエンドでコンパイルします。

import { assembleChartjs, assembleECharts, assembleVegaLite } from 'flint-chart';

const vegaLiteSpec = assembleVegaLite(input);
const echartsOption = assembleECharts(input);
const chartjsConfig = assembleChartjs(input);

Python のサポートは今後のリリースで予定されています。PyPI パッケージが公開されるまでは、 リリース済みのワークフローに npm パッケージまたは MCP サーバーを使用してください。

interface ChartAssemblyInput {
  // Bound by the HOST or by you, depending on the situation (see below).
  data: { values: any[] } | { url: string };
  semantic_types?: Record<string, string | SemanticAnnotation>;  // field → type ( ← you write this)
  chart_spec: {                               //                        ← you write this
    chartType: string;                        // e.g. "Scatter Plot"
    title?: string;                           // the headline — write one
    subtitle?: string;                        // what is measured, of whom, when, in what units
    encodings: Record<string, EncodingValue>; // channel → { field, ... } (or array)
    baseSize?: { width: number; height: number };    // target layout size, default 400×320
    canvasSize?: { width: number; height: number };  // optional hard ceiling on stretch
    chartProperties?: Record<string, any>;    // per-chart tuning (optional)
  };
  options?: Record<string, any>;              // global layout options (rarely needed)
  field_display_names?: Record<string, string>; // field → readable axis/legend title
  theme_spec?: string | { extends: string; [key: string]: any }; // preset or preset override (Vega-Lite only)
}

データのバインド方法

実行環境に合ったバインド方法を使用してください。混在させないでください。

1. MCP から直接描画する場合：行を埋め込みます。 render_chart、 compile_chart、または validate_chart を呼び出すとき、 ツールの引数は JSON です。データが小さい場合や、すでに別のツールで変換済みの場合は、 data: { values: [...] } として渡してください。MCP ツールの呼び出しに 実行環境の変数名を渡さないでください。MCP サーバーからローカル変数は参照できません。
2. MCP から直接描画する場合：ローカルファイルを参照します。 flint-chart-mcp サーバーは、ローカルの .json、.csv、または .tsv ファイルから data: { url: "..." } を読み込めます。デフォルトでは、エージェントが指定できるローカルファイルはすべて読み取り可能です（相対パスは作業ディレクトリを基準に解決されます）。セキュリティを強化したデプロイでは、--disable-file-reference（または FLINT_MCP_DISABLE_FILE_REFERENCE）を使ってローカルファイルの参照を完全に拒否する場合があります。その場合は、data.values に行をインラインで渡してください。リモート URL の取得は無効です。データを事前に変換する必要がある場合は、コーディング／データツールを使って準備したファイルを書き出し、そのファイルを参照してください。
3. アプリケーションコードやノートブックコードを生成する場合：実行時変数をバインドします。 ユーザーが Flint をコードに追加するよう求めた場合は、まず通常のデータ読み込みコードを記述し、実際の実行時の値（例：data: { values: rows }）を assembleVegaLite、assembleECharts、または assembleChartjs に渡してください。この変数を使う方法は生成コード向けであり、MCP ツールの呼び出し向けではありません。

• CSV の解析には実際のパーサー（d3.csvParse、Papa Parse、pandas）を使ってください。line.split(',') は使わないでください。"Korea, Rep." のような引用符付きの値によって後続の列がすべてずれ、ずれた測定値によってグラフが気づかないうちに変わってしまいます（ドメインが誤る、意図しない対数スケールになるなど）。
• 値は元データのまま保持し、semantic_types に読み取らせてください。Year 型として指定された数値列 year や、202501、"202501"、"2025-01" として格納された YearMonth 列は、年や月としてラベル付けされます。先に日付文字列へ変換しないでください。

仕様のみを回答する場合は、semantic_types と chart_spec の内容を返し、ホスト側でデータをバインドする方法を明記してください。以下の使用例では、data を { values: [] } として示し、「ホスト側でバインドする」ことを表しています。chart_spec と semantic_types を中心に説明してください。

グラフ化する前のデータ変換

Flint はグラフコンパイラーであり、データ加工のレイヤーではありません。グラフにグループ別の合計、期間区分、フィルター、結合、ピボット、導出比率、またはロング形式のテーブルが必要な場合は、まずホストツールでデータを変換してから、準備済みのテーブルをバインドしてください（「データのバインド方法」を参照）。存在しなくなった列ではなく、変換後の列に対してセマンティック型とチャネルを選択してください。

まず値を確認してください。データを確認せずにグラフを作らないでください。 列名だけでなく、データツールを使って実際のデータを確認してください（カテゴリ列の個別の値、測定値の最小値／最大値）。次の点にも注意してください。

• 合計値の混在。 カテゴリ列に、集計レベルの値とその内訳が混在している場合があります（例：all と cage-free／caged、または Total 地域）。合計値を内訳と一緒にグラフ化すると二重計上され、内訳が平坦化されます。積み上げ／グループ化／色分けのチャネルでは、どちらか一方だけを使ってください。
• 単位。 Percentage は、割合（0～1）とパーセント値（0～100）のどちらも受け付けます。Flint は値から判別し、どちらも % 形式で表示します。Flint 用に列の値を再スケーリングしないでください。また、二重にスケーリングしないでください。
• 実体が1つだけの場合。 分類列の個別の値が1つだけの場合、グループ別グラフは1つのマークに集約されます。本来分類に使うべき列は別の列である可能性があります。

Flint 後のスタイルカスタマイズ

構造（データ、グラフの種類、チャネル、変換、サイズ設定、プロパティ）は Flint のレベルに保ちます。Flint の仕様はポータブルなまま維持され、安全に再生成できます。有効な Flint グラフができてからバックエンド JSON に切り替え、Flint では指定できない限定的な表示変更（軸／凡例／マークの正確なスタイル、タイトル、注釈、基準線、レイアウトの仕上げ）にのみ使用します。データ、グラフの種類、フィールドのマッピング、変換を変更するためには決して使用しないでください。それらは上流で修正します。

Vega-Lite 固有のスタイルを調整する場合：

1. Flint の ChartAssemblyInput を作成して検証します。
2. 可能であれば、まず Flint グラフをレンダリングするか確認します。
3. backend: "vegalite" を指定して compile_chart を呼び出します。
4. 返された Vega-Lite の仕様に、必要最小限のスタイル／表示上の変更を加えます。
5. 編集した仕様を、ホスト環境の Vega-Lite レンダラーでレンダリングします。

編集した Vega-Lite の仕様は、もはやポータブルな Flint 仕様ではありません。render_chart には渡さないでください。render_chart は Flint の ChartAssemblyInput にのみ使用します。

見出しを書く

chart_spec.title に知見を一文で設定し、chart_spec.subtitle にその内容（何を、誰について、いつ、どの単位で測定したか）を設定します。

title:    "A pyramid that is no longer a pyramid"
subtitle: "United States population by age and sex, 2020, millions"

chart_spec.label を追加するのは、グラフが番号付きの連番、またはセクション名の下に置かれている場合に限ります。label: "Figure 2" のように指定します。テーマのキッカーのスタイルで、見出しの上に表示されます。

chart_spec.source は任意です。ユーザーが出典を指定するか、出典行を求めた場合、またはデータ自体に出所が記載されている場合にのみ追加します。source: "UN World Population Prospects 2024"（リンクにする場合は { text, href }）のように指定します。決して出典をでっち上げたり、推測したりしないでください。どのように表示されるか（「Source:」、位置、罫線、クレジット）はテーマが決定します。出典がなければ、グラフにフッターは表示されません。

chart_spec.chrome は、テーマがグラフの周囲に描画する装飾です。ヘッダーの罫線、タブ、ワードマーク、ロゴ、フッターの罫線、ハウスクレジットが該当します。グラフ自体のタイトル、ラベル、出典ではありません。テーマはデフォルトでこれを描画するため、ユーザーから削除の指示がない限り chrome は省略します。chrome: false ですべてを削除し、chrome: { logos: false }（または header、footer: false）で一部を削除します。ロゴを削除しても、クレジットの文言は残ります。

Jan、Cairo、Chrome はそれぞれ固有の種類を示しますが、26、5,300、0.42 はそうではありません。これらの種類は見出しで明示します。グラフ単体では読まれない場合（セル内のスパークラインや、独自のキャプションが付いたタイルなど）に限り、省略します。省略しても問題はありません。見出しがない場合、コンパイラーは代わりに軸タイトルを維持します。

ビジュアルテーマ（theme_spec）

2 つの形式のいずれかを使用します。ユーザーが特定ブランドに合わせた調整を求めていない限り、プリセットを優先します。

1. プリセットを使う

list_themes を呼び出して ID を選び、chart_spec の隣に配置します。

{ "chart_spec": { ... }, "theme_spec": "economist" }

id	用途
nyt	ニュースルームのグラフィック：見出しで調査結果を示し、マーク上に値を表示し、系列名を端に配置します。
economist	週刊誌の印刷版：コンパクトな構成で、デッキの上にフラットな見出しを置き、目盛りに沿って単位を繰り返し表示します。
swiss	国際タイポグラフィ様式：力強いグリッド構成、黒いタイポグラフィ、絞り込んだ赤のアクセントが特徴です。
nature	学術誌の図表：小さなパネル、単位付きの軸タイトル、近似曲線のそばに統計情報を配置します。
mckinsey	コンサルティング資料：幅広の帯ですべての値を印字し、見出しで要点を示します。
datawrapper	埋め込みウェブチャート：幅の狭い列、シンプルな見出しとデッキ、フッター下の罫線が特徴です。
powerbi	ダッシュボードタイル：コンパクトな構成で、凡例を右側に置き、最新のポイントを強調します。
powerbi-light	明るいダッシュボードタイル：白いキャンバス、細いグリッド線、鮮やかなカテゴリ別カラーが特徴です。
cartoon	遊び心のあるイラスト：温かみのある紙面、丸みのある書体、太い輪郭線、鮮やかな色が特徴です。
apple	アプリのインターフェース向けチャート：軽やかなラベル、右端の値軸、色のそばに記号を配置します。
de-stijl	デ・ステイル様式の構成：太い黒線で区切られた原色の面、傾斜ではなく段差、図の下にタイトルを配置します。
bbc	BBC News のグラフィック：大きく太字の見出し、グリッド線のみ、太いゼロ線、出典を記したフッター罫線が特徴です。
material	Material Design 3 のプロダクトチャート：紫を基調とする色調、Roboto 書体、細いグリッド線、角丸のバーが特徴です。

2. プリセットを上書きする

上書きは必要なものに絞り、ユーザーが変更したい内容だけを指定します。

{
  "theme_spec": {
    "extends": "economist",
    "id": "our-brand",
    "ink": {
      "series": {
        "single": "#6b3fa0"
      }
    }
  }
}

よく使われるシンプルな上書き項目は、ink.surface.canvas、ink.series.single、 ink.series.categorical、type.headline.family、および layout.density （"compact"、"normal"、または "airy"）です。ink.series.categorical を置き換える場合は、 系列数の多いチャートでも指定したブランドパレットが保たれるよう、 categoricalExtended も置き換えてください。

プリセット全体をコピーしたり、テーマキーを独自に作ったりしないでください。テーマが制御するのは 表示形式です。フィールド、集計、フィルタリング、並べ替えは引き続きチャート入力で指定します。ThemeSpec は Vega-Lite と Plotly に適用されます。ECharts、Chart.js、Excel では無視されます。

詳細なリファレンス： https://microsoft.github.io/flint-chart/#/documentation/theme-spec

インタラクション（interaction_spec）

ユーザーが動作を求めた場合、またはセッションの目的がデータの探索や分析である場合は、 chart_spec の隣に interaction_spec を追加します。静止画像には不要です。

{
  "chart_spec": { "chartType": "Line Chart", "encodings": { "x": "date", "y": "value", "color": "series" } },
  "interaction_spec": { "interactions": [ { "type": "brush-x" } ] }
}

各エントリは { "type": <preset>, "options": { ... } } の形式で、動作ごとに 1 つ指定します。 チャートタイプに対応するプリセットとそのオプションは、chartType を指定して list_interaction_presets から取得してください。独自のものを作成しないでください。オプションは options の下にネストし、id はエントリに配置します。

どのプリセットがリクエストに応えるか、組み合わせ方、警告の意味については、 flint-interaction-author スキル（MCP サーバー上の flint://interaction-skill）を参照してください。単一の名前付きジェスチャーを超える内容の場合は読み込んでください。対象には、意図（探索、比較、分析、外れ値の発見）、具体的な指定がない「インタラクティブにする」という依頼、複数のプリセットの組み合わせ、既存チャートへの動作の追加、画面上のチャートの更新が含まれます。

詳細なリファレンス： https://microsoft.github.io/flint-chart/#/documentation/interaction-spec

ステップ 1 — chartType を選ぶ

登録済みの名前をいずれか 1 つ、完全に一致する形で使います。Vega-Lite がデフォルトかつ 最も幅広く対応するバックエンドです。以下の表には、各 Vega-Lite チャートタイプと、それが受け付ける チャネル、調整用プロパティ（「チャートレベルのプロパティ」を参照）を記載しています。必須チャネルには注記があります。

chartType	チャネル	備考／必須
"Scatter Plot"	x, y, color, size, shape, detail, opacity, column, row	x + y が必須です。detail は、ツールチップとリンク用に、各点に視覚チャネルを使わずにフィールド（例：country）を持たせます
"Regression"	x, y, size, color, column, row	散布図 + 回帰直線です。プロパティは regressionMethod、polyOrder です
"Connected Scatter Plot"	x, y, order, color, detail, column, row	x + y が必須です。order は接続順（時間／インデックス）で、線が軌跡を描き、交差する場合があります
"Ranged Dot Plot"	x, y, color	カテゴリごとに x が2つあるダンベル図です
"Strip Plot"	x, y, color, size, column, row	ジッターを加えた点です。プロパティは stepWidth、pointSize、opacity です
"Bar Chart"	x, y, color, opacity, column, row	離散値1つ + 測定値1つです。プロパティは cornerRadius です
"Grouped Bar Chart"	x, y, group, column, row	group はクラスタリングするカテゴリです。プロパティは dodge です
"Stacked Bar Chart"	x, y, color, column, row	プロパティは stackMode です
"Pyramid Chart"	x, y, color	発散型の横棒グラフです
"Lollipop Chart"	x, y, color, column, row	プロパティは dotSize です
"Waterfall Chart"	x, y, color, column, row	color は Type 列で、値は start／delta／end のみです。符号による自動色分けを使う場合は省略します。プロパティは cornerRadius、totals です
"Gantt Chart"	y, x, x2, color, detail, column, row	x = 開始、x2 = 終了です
"Bullet Chart"	y, x, goal, color, column, row	goal（目標値）が必須です
"Histogram"	x, color, column, row	x = ビニングする測定値です。プロパティは binCount です
"Boxplot"	x, y, color, opacity, column, row	カテゴリ + 測定値です。プロパティは whiskerMethod、showOutliers、dodge です
"ECDF Plot"	x, color, detail, column, row	x = 測定値です。累積分布（ステップ線）を表示します。プロパティは showPoints です
"Heatmap"	x, y, color, column, row	color = 測定値です
"Calendar Heatmap"	x, color	x = 日付です。color = 日ごとの値（日単位で合計）です。GitHub 形式の週 × 曜日グリッドです
"Line Chart"	x, y, color, strokeDash, detail, opacity, column, row	プロパティは interpolate、showPoints です
"Sparkline"	x, y, color, detail, row, column	x + y が必須です。系列ごとに1つの小さなトレンド線を表示します（系列は color または detail から取得）。プロパティは interpolate、baseline、trendWidth です
"Bump Chart"	x, y, color, detail, column, row	時間経過に伴う順位を線で表示します
"Slope Chart"	x, y, color, detail, column, row	2期間の値の変化を表示します。直線の線分 + 端点で、カテゴリごとに1本の線を描きます
"Area Chart"	x, y, color, opacity, column, row	プロパティは interpolate、opacity、stackMode です
"Range Area Chart"	x, y, y2, color, column, row	x + y + y2 が必須です。y（下限）から y2（上限）までの半透明の帯を表示し、値軸は0ではなく帯に合わせます
"Violin Plot"	x, y, color, row	x（カテゴリ）+ y（測定値）が必須です。カテゴリごとに左右対称の KDE 密度を表示します。プロパティは bandwidth です。Vega-Lite のみ。適切な color サブグループを指定すると、2グループに分割するか、3グループ以上をグリッド表示します
"Streamgraph"	x, y, color, column, row	中央に積み上げた面グラフです
"Density Plot"	x, color, column, row	プロパティは bandwidth、stackMode（系列を積み上げます。layered は重ねて表示します）、opacity です
"Ridgeline Plot"	x, y, color	x = 測定値です。color（または離散値の y）がリッジの名前となり、それぞれ独自のベースライン上に x の KDE を表示します。測定値の y を指定すると、代わりに各系列の曲線を描画します。プロパティは overlap、order、tailCut、colorBy、perspective（プランではリッジ数に応じて skew、tilt、overlap を未設定にし、奥行きがプロットの約40%になるようにします）、skew、tilt、valueMax、markAt（true は x の目盛りにマークします。または x の値のリストを指定します。各リッジの値に点線とラベルを付け、リッジ間を結びます）、opacity、interpolate、bandwidth です。colorBy で指定しない限り、名前付きリッジは同じ色で描画されます。数値の color はグラデーションの凡例を維持します。Vega-Lite のみ
"Marginal Plot"	x, y, color, size, shape, opacity	プロットは軸の型に従います（測定値 × 測定値 = 散布図、カテゴリ × 測定値 = ストリッププロット、カテゴリ × カテゴリ = 件数のヒートマップ）。各軸に沿って分布（測定値の軸では密度、ヒストグラム、または箱ひげ図、カテゴリの軸では件数の棒グラフ）を表示し、color で分割します。密度の周辺グラフは既定で重ねて表示されます。プロパティは marginal、stackMode、bandwidth、binCount、whiskerMethod、showOutliers です。Vega-Lite のみ
"Pie Chart"	size, color, column, row	size = スライスの値（→ 角度）、color = カテゴリです。プロパティは innerRadius、sortSlices です
"Rose Chart"	x, y, color, column, row	極座標の棒グラフです。プロパティは alignment、padAngle、sortSlices です
"Radar Chart"	x, y, color, column, row	プロパティは filled、fillOpacity、strokeWidth です
"Candlestick Chart"	x, open, high, low, close, column, row	OHLC はすべて必須です
"Bar Table"	y, x, color, column, row	コンパクトな棒グラフ + 値ラベルです
"KPI Card"	metric, value, goal	大きな数値のタイルです。プロパティは behindThreshold です
"Table"	なし（encodings: {}）	指定されたとおりの行を、行内のフィールド順に1フィールド1列で表示します。data.values を行に合わせて整形し、フィールドを一覧表示し、列名には field_display_names を使用します。数値と日付は semantic_types に従って表示します。リンクと updates を受け取り、選択は送信しません
"Map"	longitude, latitude, color, size, opacity	バブルマップです。プロパティは region、projection です
"Choropleth"	id, color, detail	id = 地域キー（下記の Maps を参照）です。プロパティは region（"world"／"us"）、level（米国："state"／"county"／"auto"）、projection（世界地図）です
マップ：id に指定できる値。 Flint はキーを独自のベースマップに結び付けるため、ジオメトリや検索情報を渡す必要はありません。ワールドマップでは、国名（"India"、"DR Congo"、"United Kingdom"）、ISO 3166 の alpha-2／alpha-3 コード（"IN"、"IND"）、または ISO 数値コード（356）を、すべて 1 つの列で指定します。米国マップでは、州名、USPS コード（"CA"）または FIPS コード（6）を指定し、郡 FIPS（6037）を指定する場合は level: "county" を設定します。コードが重複する可能性がある場合は、semantic_types でキーを Country または State と宣言するか、chartProperties.region を設定してください。"CA"、"IN"、"Georgia"、小さな数値などが該当します。どの地域にも一致しないキーは描画されません。マップのマークが持つのは id、color、detail のみです。名前列をキーにしたグラフとマップを連携させるには、その列を id に指定します（名前も解決されます）。または、その列を detail に指定します（例：id: "map_id", detail: "country"）。detail はツールチップにもラベルを表示します。

ドーナツグラフ： "Pie Chart" を使い、chartProperties.innerRadius > 0 を指定します。

棒グラフの選び方（よくある混同）。 3 種類とも、x（または y）に 1 つの離散カテゴリ、さらに 1 つの指標を指定します。違いは、2 つ目のカテゴリの表示方法です。それぞれ、この 2 つ目のカテゴリを異なるチャンネルから読み取ります。

• "Bar Chart" — 単一系列に使います。複数の行で同じ x を共有する場合、color に 2 つ目のカテゴリを指定すると、セグメントが積み上げられます。棒を横並びにするには、"Grouped Bar Chart" を使い、2 つ目のカテゴリを group に指定します。
• "Stacked Bar Chart" — 2 つ目のカテゴリを color に指定し、各棒の中に積み上げセグメントとして描画します（合計値が重要な場合に使います）。stackMode（stacked／normalize／layered）で調整します。
• "Grouped Bar Chart" — 2 つ目のカテゴリを**group チャンネルに指定し、各 x クラスター内で横並び（位置をずらした）**棒として描画します（値を直接比較する場合に使います）。クラスター化するカテゴリは color ではなく group に指定してください。

目安：全体に対する内訳を比較する場合 → Stacked、横並びで値を比較する場合 → Grouped（group を使用）、単一系列の場合 → Bar。

ウォーターフォールの色は、任意のカテゴリではなく特殊な「Type」列です。 "Waterfall Chart" では、color チャンネルは start、delta、end という値を持つ type フィールド専用です。このフィールドは、どの棒をゼロ位置に固定するかを決めるもので、任意のグループ分けには使えません。color に Increase／Decrease（または up／down、gain／loss）カテゴリを割り当てないでください。上昇／下降の方向は、y の値の符号からすでに判定され、自動的に色分けされます（上昇は緑／下降は赤）。一般的なケースでは、color は指定せず、Flint に start／delta／end と各棒の符号に応じた色分けを推測させてください。合計としてどの棒を固定するかを指定するには、色フィールドではなく totals プロパティ（first／last／both）を使います。color を割り当てるのは、start／delta／end の type 列が実際にある場合に限ります。

バックエンドの対応状況。 Vega-Lite は上記すべてに対応しています。それ以外のバックエンドでは一部のみ対応しています（VL 以外のバックエンドを対象にする場合は、対応状況を確認してください）。

• ECharts が追加で対応："Gauge"、 "Funnel"、"Treemap"、"Sunburst"、"Sankey"、 "Parallel Coordinates"、"Graph"、"Tree"。
• Chart.js が対応：Scatter、Bubble、Bar、Grouped Bar、Stacked Bar、 Lollipop、Bump、Combo、Line、Area、Range Area、Pie、Doughnut、Histogram、 Radar、Rose、Slope、Connected Scatter。

入力を作成する際、ライブラリを呼び出したりソースを調べたりする必要はありません。この表から選んでください。

ステップ 2 — フィールドをチャンネルに割り当てる

各チャンネルは エンコーディングオブジェクト { field, ... }（または、{ field: "<string>" } に展開される文字列の省略形）に対応します。

"encodings": {
  "x": { "field": "weight" },
  "y": "mpg",
  "color": { "field": "origin" }
}

エンコーディングオブジェクトのフィールド（field を除き、すべて省略可能）：

フィールド	値	目的
field	列名	チャネルをデータ列に紐付けます
type	quantitative、nominal、ordinal、temporal	推論されたエンコーディングの型を上書きします（通常は不要です）
aggregate	count、sum、average、mean	メジャーチャネルに集計を強制します。セルごとに複数の行があるヒートマップでは、色を独自に集計し（Quantity や Profit のような加算型では合計、それ以外では平均）、警告が表示されます。集計方法を選ぶには aggregate を設定してください
sortOrder	ascending、descending	並べ替え順。Vega-Lite では、方向だけを指定すると意味上の順序が維持または反転されます
sortBy	マッピング済みの "x"、"y"、"color"。Vega-Lite ではデータフィールドまたは JSON 配列文字列も使用できます	カテゴリーの順序を明示します。以下の Vega-Lite の仕様を参照してください
scheme	Vega のスキーム名（例：viridis、redblue）、または低い値から順に並べた色のリスト（["#c0392b", "#f2f2f2", "#2e75b6"]）	color チャネルの配色スキーム。テーマのグラデーションより優先されます
reverse	true / false	color のみ：色のスケールの方向を反転します
mid	数値	color のみ：このチャートの発散スケールの中心値（フィールドの divergingMidpoint）を指定します
domain	[low, high]	color のみ：データの範囲に代わり、グラデーションが対象とするメジャーの範囲を指定します
bins	2 以上の整数、または 0	color のみ：連続するメジャーを指定した段階数に量子化します。0 にするとグラデーションは連続したままになります
colors	{ value: color }	color のみ：このチャートでカテゴリー値に割り当てる色（フィールドの colors）を指定します
title	文字列、または null	フィールド名の代わりにチャネルの軸またはキーに表示する名前を指定します。null にすると何も表示されません

通常、type、aggregate、sortOrder は不要です。これらは意味型から推論されます。明確な意図がある場合にのみ設定してください。

Vega-Lite の並べ替え。 月／曜日／四半期の標準順序には、並べ替えを指定しないでください。 sortOrder のみを指定すると、その意味上の順序に従います（descending は逆順になります）。 アルファベット順の月名にはなりません。意味上の順序がない場合、方向のみの指定ではフィールド固有の値順が使われます。

• sortBy: "month_number" は既存のデータフィールドで並べ替えます。デフォルトは昇順です。同じカテゴリーに複数の行がある場合は、並べ替えフィールドの最小値が使われます。
• sortBy: "y" はマッピング済みのチャネルで並べ替えます。別のチャネルを使った並べ替えはデフォルトで降順、同じチャネルを使った並べ替えはデフォルトで昇順です。x、y、color は予約済みのチャネル名であり、マッピングが必要です。
• sortBy: "[\"Mar\",\"Jan\",\"Feb\"]" はカテゴリーの順序を明示します。sortOrder: "descending" を指定すると順序が反転します。配列や Vega-Lite の sort オブジェクトではなく、JSON 配列の文字列を使用してください。要素は文字列、数値、またはブール値である必要があります。
• 月ラベルを明示的に辞書順で並べ替えるには、カテゴリーのフィールド自体で並べ替えます：{ "field": "month", "sortBy": "month", "sortOrder": "ascending" }。

不明なフィールド、マッピングされていないチャネル、無効な方向、形式が正しくない並べ替え配列は、デフォルトの順序にフォールバックせず、エラーになります。生のフィールド名による並べ替えは現在 Vega-Lite バックエンドでサポートされています。他のバックエンドでは、それぞれがサポートするチャネルの並べ替えコントロールを使用してください。選択したバックエンドに対して入力を検証してください。

複数系列（ワイド形式 → ロング形式）。 複数のメジャー列を系列としてプロットするには、x または y（この 2 つのチャネルのみ）に配列を渡します。ライブラリは列をロング形式に変換し、系列／凡例フィールドを生成します：

"encodings": { "x": { "field": "month" }, "y": ["sales", "profit"] }

配列のすべてのフィールドは量的である必要があります。また、配列形式を使う場合は color を同時にバインドできません（列の変換機能が色／凡例を管理します）。これは組み込みの唯一の形状変更機能です。transforms／fold プロパティはありません。他の形式変換（ロング形式とワイド形式の相互変換、エンコーディングでは表現できない集計、派生列、ピボット、結合）を行う場合は、まずホストツール（pandas/polars、Arquero/Array.map/SQL、またはデータ／MCP ツール）でデータを変換し、その結果を data.values として渡してください。変換手段がない場合は、存在しない変換プロパティを作り上げるのではなく、その制約を開発者に伝えてください。

ステップ 3 — セマンティック型を注釈する

これは最も重要なステップです。 セマンティック型によって、その後のすべての判断（書式設定、ゼロ基準線、配色、スケールの方向など）が決まります。各フィールドには、最も具体的な型を選んでください。登録されている型の一覧は次のとおりです。

ファミリー	セマンティック型
時間（時点）	DateTime、Date、Time、Timestamp
時間（単位）	Year、Quarter、Month、Week、Day、Hour、YearMonth、YearQuarter、YearWeek、Decade
時間（期間）	Duration
測定値（量）	Amount、Price、Quantity、Count、Number
測定値（比率）	Percentage
測定値（正負・発散）	Profit、PercentageChange、Sentiment、Correlation
測定値（物理量）	Temperature
離散値／順位	Rank、Score、ID
地理（座標）	Latitude、Longitude
地理（場所）	Country、State、City、Region、Address、ZipCode
カテゴリ	Category、Name、Status、Boolean、Direction、Range
フォールバック	Unknown

時間型は、Flint が値をどのように読み取るかも指定します。YearMonth は 202501、2025-01、2025/1、01/2025、2025M01、Jan 2025、2025-Jul、July-2025、または Jul '25 を受け付けます。Date は 20250115、2025/01/15、Jan 15, 2025、または 15-Jan-2025 を受け付けます。値はそのまま渡してください。型が指定されていないフィールドが別の形式として解釈されることはありません。

適切な型を選ぶと、次の処理が自動で行われます。

• Price / Amount → 通貨形式、ゼロ基準線、順次配色
• Temperature → 発散型の配色、ゼロ基準線の強制なし
• Correlation → 固定された [-1, 1] の発散ドメイン
• Rank → 軸を反転（1 が上）、離散色
• Date / DateTime → 粒度に応じて書式が自動調整される時間軸
• Percentage → パーセント形式、0～100 のドメインを考慮

判断がつかない場合は、数値には Quantity、文字列には Category、日付形式の値には Date / DateTime を使ってください。型名を独自に作らないでください。

型名以上の情報を伝える

型だけでは、分かっていることを十分に表せない場合、フィールドのエントリーには文字列ではなくオブジェクトを指定できます。

"semantic_types": {
  "anomaly": { "semanticType": "Quantity", "unit": "°C", "divergingMidpoint": 0 },
  "rating":  { "semanticType": "Score", "intrinsicDomain": [1, 5] }
}

• unit — Flint が単位を表示することを許可する任意の指定です。データまたは周辺の文脈から測定内容が明らかで、単位を表示することで読者による数値の解釈が大きく変わる場合にのみ追加します。Duration のような型、life_expectancy のようなフィールド名、あるいはもっともらしく見える値だけでは、根拠として不十分です。
  • 標準的なコードを優先します。"USD"、"°C"、"kg"、"km/h"、"min"。
  • 慣例的な短縮単位は正規化され、値の横に表示されることがあります（USD → $、hours → hr）。
  • "years" のような語句による単位は、各値の後に繰り返し表示するのではなく、フィールド名の横に一度だけ field (years) の形式で表示します。
  • 説明文を unit に指定しないでください。"per working-age resident" や "constant 2024 prices" のような補足は、サブタイトルに記載します。
  • 意味、スケール、または分母が不確かな場合は、unit を省略します。Flint は、意味的な型やフィールド名から表示単位を推測しません。
• intrinsicDomain — 有界スケールの場合のみ、フィールド固有の範囲を指定します。5段階評価なら [1, 5]、パーセンテージスコアなら [0, 100] です。上限のない尺度には使用しません。
• divergingMidpoint — 発散スケールにおける中間色の位置を指定します。読者が何と比較しているか分かる場合は設定し、分からない場合は省略します。
• sortOrder — データ内の順序が意図した順序ではなく、かつアルファベット順でもない場合に、カテゴリを表示する順序を指定します。["Low", "Medium", "High"]。少数のカテゴリに使用し、長いリストには使用しません。
• colors — データに読者が期待する慣例がある場合に、特定の値に対応する色を指定します。{ "DFL": "#0793AB", "Republican": "#A1000F" }。値に対して照合されます（大文字と小文字は区別されません）。指定されていない値にはパレットが適用され、その際、指定済みの色はスキップされます。実際の慣例（政党、ブランド、資産クラスなど）にのみ使用し、チャートの見た目を変える目的では使用しないでください。パレットはテーマによって決まります。
• polarity — "higher-is-better" または "lower-is-better"：発散色のどちら側を警告色にするかを指定します。符号付きの尺度（Profit、PercentageChange）は、それ自体で higher-is-better と解釈されます。コスト、エラー、チャーン、遅延では "lower-is-better" を設定すると、どのテーマでも、低い値ではなく高い値が暖色側になります。

ステップ 4 — 仕様を記述する

3 つのステップを 1 つの ChartAssemblyInput にまとめ、データは「データのバインド方法」の説明に従ってバインドし、見出しは「見出しの記述」の説明に従って指定します。

{
  "data": { "url": "sales.csv" },
  "semantic_types": { "month": "YearMonth", "revenue": "Amount", "region": "Region" },
  "chart_spec": {
    "chartType": "Line Chart",
    "title": "Europe climbed every month after the April dip",
    "subtitle": "Revenue by region, $m",
    "encodings": { "x": { "field": "month" }, "y": { "field": "revenue" }, "color": { "field": "region" } }
  },
  "theme_spec": "economist"
}

リクエストで指定された場合にのみ、theme_spec、chartProperties、interaction_spec、または updates を追加します。MCP ツールを使う場合は、validate_chart で検証し、レポートの指示に従って仕様を修正してから、仕様全体を chart として show に渡します。MCP ツールを使わない場合は、「検証チェックリスト」を実行します。

チャートレベルのプロパティ（chartProperties）

chartProperties は、チャートごとに設定できる任意の調整マップです。ユーザーがその動作を求めた場合にのみプロパティを設定してください。デフォルト値は適切に設定されています。これらはデザイン上の選択であり、スタイルの上書きではありません（色、フォント、目盛りは引き続き派生されます）。値は表示された範囲内に制限されます。

チャートの種類	プロパティ	型／範囲（デフォルト）	効果
棒グラフ	cornerRadius	0–15（0）	棒の角を丸くします（px）
エリア／積み上げ棒グラフ	stackMode	stacked | normalize | center | layered（未設定）	積み上げの動作です。normalize = 100％、center = ストリームグラフ
密度プロット	stackMode	normalize | layered（未設定 = 積み上げ）	layered は系列を半透明で重ねます
密度プロット	opacity	0.1–1（0.7）	レイヤー表示する系列の不透明度
周辺分布プロット	stackMode	stacked（未設定 = レイヤー表示）	密度の周辺分布を重ねずに積み上げます
グループ化棒グラフ／箱ひげ図	dodge	auto | local | global（auto）	local はカテゴリごとにまばらなグループを詰めて表示し、global はグループの配置を揃えます。ユーザーから指定がない限り、auto のままにします
折れ線／エリア／スパークライン	interpolate	linear | monotone | step | step-before | step-after | basis | cardinal | catmull-rom（linear）	曲線の形状
折れ線／ECDFプロット	showPoints	boolean（false）	折れ線上に点マーカーを描画します
スパークライン	baseline	mean | zero | median | none（mean）	スパークラインの各行に基準線を表示します
スパークライン	trendWidth	80–600（240）	ミニ折れ線プロットの幅（px）
箱ひげ図	whiskerMethod	iqr | minmax（iqr）	ひげのルール（Tukeyの1.5×IQR、または最小値–最大値）
箱ひげ図	showOutliers	boolean（true）	外れ値の点を表示します（Tukeyのみ）
エリア	opacity	0.1–1（0.7）	塗りつぶしの不透明度
散布図	opacity	0.1–1（1）	点の不透明度
ストリッププロット	stepWidth	10–100（20）	ジッターの広がり
ストリッププロット	pointSize	0–150（0=自動）	点のサイズ
ストリッププロット	opacity	0–1（0=自動）	点の不透明度
ヒストグラム	binCount	5–50（10）	ビンの数
密度プロット／リッジライン／周辺分布プロット	bandwidth	0.05–2（0=自動）	カーネルの帯域幅
リッジライン	overlap	0.5–4（1.8）	最も高いリッジが何本分の基準線まで達するか
リッジライン	order	mean、reverse（未設定 = 指定順。量的系列は最小値が手前）	平均値の高い順に上から並べるか、逆順にします
リッジライン	tailCut	0–0.2（0）	各リッジの密度がピークのこの割合以上となる範囲に切り詰めます
リッジライン	colorBy	series、x（未設定 = 単色）	名前付きリッジはデフォルトで同じ色を使います。series は各リッジに色を付け、x は x 軸に沿ったグラデーションで各リッジを塗ります
リッジライン	perspective	boolean（false）	透視図法で見た床面にリッジを立てます。skew、tilt、overlap が未設定の場合、奥行きがプロット幅のおよそ40％を占め、リッジが追加されるほど高さの割合が増えるように設計されています。奥行きの名前、端の目盛り、値の目盛りは、重なる前に順に間引かれます（軸に沿ったもの、次に段、最後にn個おき）
リッジライン	skew	0–0.4（0）	透視図法：背面のリッジを x の範囲のこの割合だけ左にずらします
リッジライン	tilt	0–6（0）	透視図法：x 軸が範囲全体で基準線何本分上昇するかを指定します。ラベルは軸の端に沿って配置されます
リッジライン	opacity	0.1–1（0.5）	リッジの不透明度。Range Area Chartと同様です。設定がない場合、透視図法では不透明度が1になります
リッジライン	valueMax	number（0 = 最も高いピーク）	透視図法：リッジの高さ全体が表す値です。背面左側の値軸で読み取ります
リッジライン	markAt	boolean | number[]	範囲内の x 軸目盛り（true）または指定した x の位置で、各リッジの値にマーカーとラベルを付けます。同じ x にあるリッジ間のマーカーは破線で結ばれます
周辺分布プロット	marginal	density | histogram | boxplot（density）	各周辺部で量的軸に沿って描画するものです。カテゴリ軸には度数の棒が表示されます
円グラフ	innerRadius	0–100（0）	ドーナツの穴のサイズ（>0 → ドーナツ）
円グラフ／ローズチャート	sortSlices	none | descending | ascending（none）	スライスの値に基づき、扇形と凡例の順序を並べ替えます
ローズチャート	alignment	left | center（left）	扇形の配置
ローズチャート	padAngle	0–0.1（0）	スライス間の間隔
ロリポップチャート	dotSize	20–300（80）	円のサイズ（px）
ウォーターフォールチャート	cornerRadius	0–8（0）	棒の角を丸くします
ウォーターフォールチャート	totals	auto | none | first | last | both（auto）	合計としてゼロを基準にする棒を指定します（Type列がない場合のみ）
ウォーターフォールチャート	showTextLabels	boolean（false）	showValueLabels の旧式の表記です。引き続き使用できます
棒グラフ／グループ化棒グラフ／積み上げ棒グラフ／ロリポップチャート／ピラミッドチャート／円グラフ／ドーナツチャート／ヒートマップ／ウォーターフォールチャート	showValueLabels	boolean	マーク上に数値を表示します。テーマの有無にかかわらず動作します。未設定の場合、この密度での各ハウス独自の慣習に従い、ハウスが指定されていなければ非表示になります。そのため、コンパイラーが報告するデフォルト値は常に実際の状態を反映します。1つのチャートでこの動作を上書きするには設定してください。読み取れる数値を表示するにはマークが密集しすぎている場合や、テンプレート自体がテキストを表示している場合は、適用対象外として報告され無視されます。そのため、設定しても何も起きない制御項目にはなりません。積み上げ棒グラフでは、各セグメントの中央にそのセグメントの値が表示されます（端に表示すると累計値に見えてしまいます）。1行のテキストが収まらないほど細いセグメントにはラベルが表示されません。また、正規化された積み上げでは、長さが示すのは割合であるため、実際の値ではなく各セグメントの割合が表示されます。表示される数値はおよそ有効数字3桁に丸められます。値が大きくなるとk／Mの接尾辞が付き、系列内の最小値も意味のある値として読めるよう、小数点以下の桁数が調整されます。そのため、生の値が 3.14159265 なら 3.14 と表示され、0.001 から 5000 までの系列も両端の値を読み取れます。丸めた結果、サイズの異なる2つのマークに同じ数値が表示されたり、ゼロ以外の値が 0 と表示されたりすることはありません。ハウスがこれより粗い精度を指定している場合は、ラベルがマークと一致するまで桁数を増やします。
回帰	regressionMethod	linear | log | exp | pow | quad | poly（linear）	フィッティング方法
回帰	polyOrder	1–5（3）	多項式の次数（poly の場合）
レーダーチャート	filled	boolean（true）	多角形を塗りつぶします
レーダーチャート	fillOpacity	0–0.5（0.15）	多角形の塗りつぶしの不透明度
レーダーチャート	strokeWidth	0.5–4（1.5）	線の幅
KPIカード	behindThreshold	0–1（0.5）	色分けに使う値／目標比のしきい値
マップ	region	us | world | auto（auto）	地理的な範囲
マップ	projection	mercator | equalEarth | orthographic | stereographic | conic | mollweide	地図投影法
横断的なプロパティ（関連する場合、位置ベース／ファセットチャートに適用します。デフォルト以外の動作を強制するときだけ設定します）：

• independentYAxis（boolean）— ファセットチャート：パネルごとに独自の y スケールを設定します。
• logScale_x / logScale_y（boolean）— 対数軸を強制します。
• includeZero_x / includeZero_y（boolean）— 軸に 0 を含めるよう強制します。
• xAxisType / yAxisType（temporal | nominal）— 時間フィールドを離散的な帯として描画する（またはその逆）よう強制します。
• labelOverflow（ステップのリスト）— 帯に収まらないパス x カテゴリ名に適用する処理です。省略した場合、名前は折り返されてから縦向きになり（必要であれば省略されます）、すべての名前が表示されます。時刻、日付、年、順位の連続データは折り返されてから、きりのよい値（16:45、17:00）だけが横向きで表示されます。年をすべてラベル表示したい場合は ["wrap", "rotate90"]、45°のラベルにしたい場合は ["wrap", "rotate45", "rotate90"] のように、ユーザーから指定があった場合のみ設定します。ステップ：wrap、skip（連続データのみ）、rotate45、rotate90。

パラメーターの上書き — 使用するタイミング

上書きもできますが、セマンティック型に判断を委ねることを優先してください。ユーザーの意図がデフォルトと本当に矛盾するときだけ、上書きを使用します。

• 集計方法を強制する： encodings.y = { field: "sales", aggregate: "sum" }。
• カテゴリ軸を指標で並べ替える： encodings.x = { field: "name", sortBy: "y", sortOrder: "descending" }。
• カラースキームを選択する： encodings.color = { field: "region", scheme: "tableau10" }。
• ユーザーから指定があった場合にカラースケールを制御する： encodings.color = { field: "net", scheme: ["#c0392b", "#f2f2f2", "#2e75b6"], mid: 0, bins: 5 }。反転するには reverse: true、範囲を固定するには domain: [-50000, 50000] を追加します。これらはテーマより優先されます。
• 推定された型を上書きする： encodings.x = { field: "year", type: "ordinal" }（例：年を離散的な帯として扱います）。
• 読みやすいフィールドタイトルを使用する： field_display_names = { percentageOfCountries: "Percentage of countries" }。 エンコーディングは実際の列名に紐付けたままにします。Flint は表示名を軸タイトルと凡例ヘッダーに使用します。
• チャートのサイズを変更する： Flint は 2 つの数値を基準にサイズを決定します。baseSize（目標サイズ。デフォルトは 400×320）と、超えることのない上限の canvasSize です。データが密な場合、チャートは baseSize から上限に向けて拡大します。
  • 密なデータでは拡大できる、余裕のあるサイズにしたい → chart_spec.baseSize = { width, height } を設定します。
  • 収める必要のある固定の領域にしたい → chart_spec.canvasSize = { width, height } のみを設定します。チャートは領域いっぱいに表示され、収まるように縮小され、はみ出すことはありません。指定したとおりに表示されます。
  • 両方を設定する → baseSize を目標とし、canvasSize に向けて拡大しますが、それを超えることはありません。
• 対数軸／ゼロ基準線を強制する： 上記の logScale_* / includeZero_* チャートプロパティを使用します。

グローバルなレイアウト調整はトップレベルの options オブジェクトにあります（例：addTooltips、帯のパディング、ファセットのサイズ設定）。作成時に必要となることはほとんどないため、指定がない限り省略してください。

使用例

各例の data はプレースホルダーです。ホストが実際の行または URL をバインドします。作成するのは chart_spec と semantic_types のみです。

散布図

ユーザー：「車の重量と燃費を、原産地別に色分けしてプロットしてください。」

{
  "data": { "values": [] },
  "semantic_types": {
    "weight": "Quantity",
    "mpg": "Quantity",
    "origin": "Country"
  },
  "chart_spec": {
    "chartType": "Scatter Plot",
    "encodings": {
      "x": { "field": "weight" },
      "y": { "field": "mpg" },
      "color": { "field": "origin" }
    },
    "baseSize": { "width": 400, "height": 300 }
  }
}

ファセット付き売上棒グラフ、値の降順

ユーザー：「製品ライン別の売上を、大きい順に、地域ごとに 1 つのパネルで表示してください。」

{
  "data": { "values": [] },
  "semantic_types": {
    "product_line": "Category",
    "revenue": "Amount",
    "region": "Region"
  },
  "chart_spec": {
    "chartType": "Bar Chart",
    "encodings": {
      "x": { "field": "product_line", "sortBy": "y", "sortOrder": "descending" },
      "y": { "field": "revenue" },
      "column": { "field": "region" }
    }
  }
}

時系列、複数系列（配列を使ってワイド形式からロング形式へ変換）

ユーザー：「月別の売上と利益を折れ線グラフで表示してください。」

{
  "data": { "values": [] },
  "semantic_types": {
    "month": "YearMonth",
    "sales": "Amount",
    "profit": "Profit"
  },
  "chart_spec": {
    "chartType": "Line Chart",
    "encodings": {
      "x": { "field": "month" },
      "y": ["sales", "profit"]
    },
    "chartProperties": { "interpolate": "monotone", "showPoints": true }
  }
}

ドーナツグラフ（Pie + innerRadius）、値を size に指定

ユーザー：「ベンダー別の市場シェアをドーナツグラフで表示してください。」

Pie／ドーナツでは、スライスの値を size（角度として描画）に、カテゴリを color に割り当てます。データはすでにロング形式（ベンダーごとに 1 行）です。

{
  "data": { "values": [] },
  "semantic_types": {
    "vendor": "Category",
    "share": "Percentage"
  },
  "chart_spec": {
    "chartType": "Pie Chart",
    "encodings": {
      "size": { "field": "share" },
      "color": { "field": "vendor" }
    },
    "chartProperties": { "innerRadius": 60 }
  }
}

ブレットチャート（KPI と目標値の比較）

ユーザー：「担当者ごとの売上をノルマと比較して表示してください。」

{
  "data": { "values": [] },
  "semantic_types": {
    "rep": "Name",
    "sales": "Amount",
    "quota": "Amount"
  },
  "chart_spec": {
    "chartType": "Bullet Chart",
    "encodings": {
      "y": { "field": "rep" },
      "x": { "field": "sales" },
      "goal": { "field": "quota" }
    }
  }
}

してはいけないこと

• データを再出力しないでください。 列名で列を参照し、ホストに data（URL、変数、または小さなリテラル）をバインドさせます。大規模なデータセットを貼り付けないでください。
• バックエンドの仕様を直接記述しないでください。 ChartAssemblyInputを記述してから、 アセンブラーを呼び出します。それがこの仕組みの目的です。
• 変換を勝手に作らないでください。 組み込みの形状変更は、x／yの配列形式だけです。 データの形状がチャートに合わない場合は、その旨を伝え、ホストに形状変更を依頼します。
• フィールド名を勝手に作らないでください。 実在する列だけを、正確な表記で参照します。 データの形状がチャートに合わない場合は、存在しない列名を推測するのではなく、上流で形状変更します。
• デフォルトの意図と競合しない限り、type／aggregate／sortOrderを設定しないでください。
• 色、フォントサイズ、軸の目盛り数を指定しないでください。 これらはコンパイラーが決定します。ユーザーは出力仕様を微調整します。例外は、ユーザーが指定した色のマッピング（ブランドカラーのグラデーション、固定ビン、ピボット）です。その場合は、colorエンコーディングのscheme、reverse、mid、domain、bins、colorsを使用します。
• 意味的な型名を勝手に作らないでください。 該当するものがない場合は、ファミリーのデフォルト（Quantity、Category、Date）を使用します。
• チャンネル／型を調べるためにライブラリを呼び出さないでください。 このドキュメントが記述時のリファレンスです。

検証チェックリスト

返答する前に、以下を確認します。

1. chartTypeが、対象バックエンドでサポートされる登録済みの正確な名前であること。
2. encodingsで参照するすべてのfieldが、実在する列名であること。
3. エンコードされたすべてのフィールドに、semantic_types内のエントリー（具体的な型）があること。
4. チャートの種類で必須のチャンネルが指定されていること（例：Bullet→goal、 Candlestick→open/high/low/close、Pie→size+color）。
5. chartPropertiesのキーがそのチャートの種類で有効で、許容範囲内であること。
6. 大量のデータをインライン化したり、派生スタイルを手作業で調整したりしていないこと。
7. 積み上げ、グループ化、または色分けされたチャンネルで、データに構成要素と混在する埋め込みの合計／小計レベル（例：all／totalの行）が含まれていないこと。