datapackage

Frictionless Data Package ガイド

このスキルは、Frictionless Data Package の記述子ファイル （datapackage.json）で記述された、あらゆるデータセットを対象とします。特定の公開者やデータの内容に依存せず、仕様に準拠するすべての datapackage で使えるよう、汎用的に設計されています。

PUDL 固有の知識（S3 バケットのパス、テーブルの階層に関する規約、データソースの背景、利用上の警告）については、このスキルに加えて pudl スキルも使用してください。

datapackage.json とは？

datapackage.json は、表形式データのリソース群を記述する JSON ファイルです。各リソースは 1 つのテーブル（またはファイル）を表し、次の情報が含まれます。

• name：機械可読な識別子
• description：人が読める説明。処理に関する注記、主キー、利用上の警告などが含まれることがあります
• path：実際のデータファイルのファイル名または URL
• schema.fields：列の一覧。各列には name と description が含まれます
• schema.primaryKey：このリソース内の行を一意に識別するフィールドまたはフィールド群
• schema.foreignKeys：このリソースのフィールドから、別のリソースの主キーへのリンクとして宣言された情報です。結合または集計の前に確認してください（メタデータのクエリを参照）

このファイルは大きい場合があります（数百のリソース、数メガバイトの JSON）。必ず必要な情報だけを選択してクエリし、ファイル全体をコンテキストに読み込まないでください。

依存関係の確認

メタデータをクエリする前に、jq が利用可能であることを確認してください。

command -v jq

見つからない場合は、次のインストール方法をユーザーに案内してください。

• macOS：brew install jq
• Linux（apt）：sudo apt install jq
• Linux（conda）：conda install jq
• Windows：winget install jqlang.jq

データの読み込みと SQL クエリには、attach-db と query の各スキルがインストールされている必要があります（install-duckdb も任意でインストールしてください）。duckdb/duckdb-skills からインストールしてください。

ワークフローの概要

1. 記述子を見つける — datapackage.json を探すか、ダウンロードします（以下を参照）。
2. メタデータを必要な分だけクエリする — jq を使い、必要な情報だけを抽出します。 メタデータのクエリを参照してください。
3. 警告を提示する — リソースを提示する前に、必ず利用上の警告を確認します。
4. 結合または集計の前にキーを確認する — タスクで 2 つのリソースを組み合わせる場合、または 1 つのリソースを集計する場合は、同じ名前や似た名前の列で結合するのではなく、まず各リソースの schema.primaryKey と schema.foreignKeys を調べます。メタデータのクエリ：リソースの結合を参照してください。
5. 検証する (任意) — データが記述子と実際に一致するかをユーザーが知りたがっている場合、または不審なパッケージを調査している場合は、frictionless validate を使用します。Frictionless Validateを参照してください。
6. データを読み込む (任意) — ユーザーが実際のデータのクエリまたは調査を明示的に希望する場合に限ります。データファイルは大きいことがあり、リモートアクセスには時間や費用がかかる場合があります。ユーザーが希望していることを確認せず、メタデータの検索に続けてデータを読み込まないでください。ストレージバックエンドを参照してください。

リファレンス一覧

• メタデータのクエリ — 記述子を見つけ、jq で必要な情報だけをクエリし、利用上の警告を提示します
• ストレージバックエンド — 記述子で参照される Parquet、DuckDB、SQLite、または CSV ファイルからデータを読み込みます
• Frictionless Validate — frictionless CLI を使用してパッケージの検証、データ品質の確認、スキーマの推測、未知の記述子の診断を行います。ユーザーが記述子を検証したい場合、データがスキーマと一致するか確認したい場合、または frictionless ツールでパッケージについて何が分かるか知りたい場合に参照してください

コミュニティのパターンとレシピ

datapackage 標準は許容範囲が広く、公開者が独自のフィールドを追加することもよくあります。 すぐに知っておく価値のある慣習が 2 つあります。

• カスタムフィールド — 公開者が追加する標準外のキーは一般的であり、有効です。 _ 接頭辞の慣習は、システムが生成したキーやプラットフォーム固有のキー（例： _cache、_platformVersion）を示します。一部の公開者は接頭辞なしでカスタムキーを追加します （例：パッケージレベルの単位レジストリや、リソースごとの来歴メタデータ）。不明なフィールドは エラーではなく、情報メタデータとして扱ってください。
• 圧縮リソース — .gz または .zip のパスを持つリソースには、 明示的な "compression": "gz" フィールドが設定されている場合があります。bytes と hash の フィールドは、展開後の元ファイルではなく、圧縮ファイルに適用されます。

その他のパターン（カタログ、バージョン管理、外部外部キー、翻訳サポート、 フィールド間の関係など）については、必要に応じて該当するページを取得してください。

• v1 のパターン：https://specs.frictionlessdata.io/patterns/
• v2 のレシピ：https://datapackage.org/recipes/caching-of-resources/（サイドバーまたは 次へ／前へリンクから移動してください。インデックスページはありません）

どちらのページも、コミュニティの慣習の多くを同様に扱っています。作業対象の記述子のバージョンに 合ったページを参照してください。

関連スキル

このスキルは、実際のデータクエリを以下に委任します。

• /attach-db — .duckdb または .sqlite データベースファイルをアタッチし、 クエリ用の永続セッションを設定します
• /query — アタッチ済みデータベース、アドホックファイル（Parquet、CSV、リモート HTTPS/S3）、 および datapackage.json 自体を含む JSON ファイル（DuckDB の read_json 経由）に対して、 SQL または自然言語のクエリを実行します

これらのスキルをインストールしておく必要があります。プロジェクトルートの skills-lock.json を参照してください。

主な制約

• 大原則：datapackage.json 全体をコンテキストに読み込まないでください。 数百のリソースを含み、 サイズが数メガバイトに達することがあります。常に必要な項目だけをクエリしてください。
• リソースを提示する前に、説明文全体を読んでください。 説明文には、処理上の注意事項、主キーの慣習、 データの来歴、既知の制限事項に関する注意など、重要なコンテキストが含まれていることがよくあります。 省略しないでください。
• Python パッケージのインストールには uv を使用してください — pip install <package> より uv add <package> を優先してください。uv はより高速で、グローバルではなく仮想環境にインストールします。 uv が利用できない場合（command -v uv が何も返さない場合）に限り、pip を使用してください。
• 記述子のメタデータのクエリに Python を使用しないでください。 ここでは Python は適切なツールではありません。 JSON 全体をメモリに読み込むため（上記の大原則に反します）、不要な依存関係が増え、 リモートの記述子も簡単には扱えません。メタデータのみの作業には jq を使用し、 メタデータのクエリとデータのクエリを組み合わせる必要がある場合は DuckDB を使用してください。 Python が適切なのは、必要なテーブルと列がすでにわかっている場合に、pandas または polars を使って データを読み込むときだけです。

スキーマのリファレンスとバージョンの判定

Frictionless Data Package 標準には、広く使われているバージョンが 2 つあります。解析する前に、最上位の記述子からバージョンを特定してください。

存在するフィールド	バージョン	値の例
"$schema"	v2.0	"https://datapackage.org/profiles/2.0/datapackage.json"
"profile"	v1.0	"tabular-data-package" または "data-package"
どちらもなし	判定不能（v1 を基準として扱う）	—

解析に影響するバージョン間の主な違い：

• コントリビューター — v1 では "role": "author"（単数形の文字列）、v2 では "roles": ["author"]（配列）です。実際のデータではどちらも見られる場合があります。
• 名前のパターン — v1 では小文字の [-a-z0-9._/] のみが厳密に許可されますが、v2 では制限がありません。
• version フィールド — v2 にはありますが、v1 にはありません。

同梱スキーマ：

• assets/datapackage-v1.schema.json — v1.0 （JSON Schema draft-04）。FERC XBRL パッケージや、多くの古いデータセットで使用されています。
• assets/datapackage-v2.schema.json — v2.0 （JSON Schema draft-07）。現行の標準です。正規のバージョンは常に次の場所にあります： https://datapackage.org/profiles/2.0/datapackage.json

記述子で有効なフィールドを確認する場合や、プログラムで検証する場合は、適切なスキーマを参照してください。