coral-create-source-spec

Coral Create ソース仕様

タスクが Coral ソース仕様の作成または修正である場合は、このスキルを使用します。

目標

次の機能で動作する、有効でクエリ可能な Coral ソース仕様を作成します。

• coral source lint <path>
• coral source add --file <path>
• coral source test <name>
• coral sql
• coral.tables および coral.columns
• ソース変数とシークレット用の coral.inputs

デフォルトモード

外部開発者向けのスタンドアロンソースの作成をデフォルトとします。

つまり、次のようにします。

• YAML ソース仕様ファイルを作成する
• 早い段階で coral source lint <path> を使って lint を実行する
• ソースとして動作を確認する必要がある場合は、coral source add --file <path> を使って Coral に追加する
• クエリを実行して検証する
• 仕様の形が正しくなるまで繰り返す

ユーザーが明示的に Coral リポジトリを編集している場合に限り、Coral リポジトリの構成に切り替えます。

出力モード

• 外部向けの作成：
  • ./my-source.yaml などのスタンドアロンソース仕様を作成する
  • coral source lint ./my-source.yaml で構造を検証する
  • Coral 経由でクエリを実行する必要がある場合は、coral source add --file ./my-source.yaml で読み込む
• Coral リポジトリへのコントリビューション：
  • コミュニティソース仕様は sources/community/<name>/manifest.yaml に記述する
  • ユーザーがバンドル済みコアソースを意図的に変更する場合に限り、コアソース仕様を sources/core/<name>/manifest.yaml に記述する
  • ソースの基本的なスモークテスト／接続チェック用に、代表的な test_queries を追加する
  • coral source test <name> とリポジトリのチェックで検証する

ワークフロー

1. プロバイダーの API ドキュメントを読むか、ローカルデータセットを調べます。
2. 小さなテーブルと少数のカラムから始めます。
3. 次を定義します。
   • ソースのメタデータ
   • バックエンド
   • ベース URL またはファイルの場所
   • 認証
   • 変数とシークレット
   • シークレットの認証情報取得方法。プロバイダーがブラウザーベースのセットアップに対応している場合は、OAuth を含めます
   • 別個の kind: identity マニフェストを作成する場合は、ID のセットアップ入力と OAuth メソッドの設定
   • テーブル
   • ソースのスコープ内にあるパラメーター化されたエンドポイント用のテーブル関数
   • フィルター
   • レスポンスの抽出
   • ページネーション
   • 型付きカラム
4. ソース仕様を lint します。
   • coral source lint <path>
5. 適切なモードでソースを検証します。
   • スタンドアロン仕様：coral source add --file <path> を実行し、coral sql で確認します
   • coral source add はデフォルトで非対話型です。各入力の key は、対応する環境変数から読み取られます。実行前に必要な変数とシークレットをエクスポートするか、プロンプトを表示する場合は --interactive を渡します。
   • OAuth 認証情報メソッドの場合は、対象のシークレットに環境変数を設定せずに coral source add --interactive --file <path> を実行すると、Coral に作成済みの認証情報の選択肢が表示されます
   • リポジトリ内のソース、またはすでに名前が付いているソース：coral source test <name>
6. 公開される構造を確認します。
   • coral.tables を確認し、表示されるテーブル、説明、ガイド、必須フィルターを調べます。メタデータクエリは LIMIT／OFFSET を使って範囲を制限します
   • coral.table_functions を確認し、ソースのスコープ内にある関数、説明、ガイド、引数、結果カラム、種類、検索制限を調べます
   • coral.columns を確認し、is_virtual と is_required_filter を含む標準のカラムメタデータを調べます。対象を1つのテーブルに絞るか、カラム数が多い場合はページ分割します
   • coral.filters を確認し、正規化されたテーブルフィルターの名前、型、モード、必須フラグ、説明を調べます
   • coral.inputs を確認し、変数、シークレット、デフォルト値、ヒント、必須フラグを検証します
7. coral sql で代表的なテーブルにクエリを実行します。
8. coral source test に依存する場合は、ソースの基本的なスモークテスト／接続チェックとなる test_queries を設定します。
9. 仕様を調整して、手順を繰り返します。

作成ルール

• 小さく始め、テーブルの対応範囲を段階的に広げます。
• ソースマニフェストのスキーマを、作成時の参考と構造の検証の両方に使用します：https://github.com/withcoral/coral/blob/main/crates/coral-spec/src/schema/source_manifest.schema.json
• シークレットではない設定にはソース変数を使用します。
• 認証情報にはソースシークレットを使用します。
• OAuth 対応サービスでは、inputs.<TOKEN>.credential.methods[] を type: oauth として設定し、セットアップを定義します。実行時の auth またはリクエストヘッダーは、同じシークレット入力を参照するようにします。
• OAuth 認証方法では、デバイスコード、認可コード、クライアントクレデンシャルの各フローがサポートされています。認可コードフローでは、flow.type: authorization_code を設定し、flow.pkce を required または disabled に明示的に設定します。リダイレクト URI にはループバックの http://127.0.0.1 または http://localhost を使用します。プロバイダーアプリまたは動的クライアント登録エンドポイントで localhost のポートを可変にできる場合は redirect_uri_port_mode: random を選択し、ユーザーが正確なゼロ以外のリダイレクト URI を登録できる場合に限り fixed を選択します。ブラウザーから Coral を実行しているマシンにアクセスできない場合、CLI はターミナルに貼り付けられた最終的なループバックリダイレクト URL も受け付けます。そのため、ユーザーが SSH、VM、その他ブラウザーと実行環境が分かれた環境で Coral を実行する可能性があるという理由だけで、認可コード OAuth を除外しないでください。デバイスコードフローでは、flow.type: device_code、endpoints.device_authorization_url、endpoints.token_url、および公開クライアント ID または client.dynamic_registration のいずれかを宣言します。リダイレクト URI のフィールドは省略し、静的クライアントシークレットは宣言しないでください。クライアントクレデンシャルフローでは、flow.type: client_credentials、endpoints.token_url、client.id.input、client.secret.input、client.secret.transport を宣言します。リダイレクト URI のフィールド、認可エンドポイント、デバイス認可エンドポイント、PKCE、動的クライアント登録は省略してください。
• 認可コードまたはデバイスコードのプロバイダーが OAuth 動的クライアント登録に対応している場合、共有の公開クライアント ID をハードコードする代わりに、client.dynamic_registration.registration_url を優先します。Coral は常にネイティブクライアントを登録します。ソース仕様では、web 動的クライアント登録アプリケーションタイプを設定できません。登録されたクライアントタイプに合わせて、token_endpoint_auth_method を none、client_secret_basic、または client_secret_post に設定します。プロバイダーがリフレッシュトークン付与を許可するクライアントの登録に対応している場合に限り、request_refresh_token_grant: true を設定します。OAuth で保護された Streamable HTTP MCP サーバーで、プロバイダーがリソースインジケーターを必要とする場合は、oauth.resource に MCP サーバーの URL を設定します。
• OAuth URL フィールドでは、テナント ID やドメインなど、シークレットではないエンドポイント構成要素に対して、宣言済みの kind: variable 入力を {{input.KEY}} でテンプレート化できます。対象には endpoints.*、resource、client.dynamic_registration.registration_url が含まれます。OAuth URL からシークレット入力、フィルター、関数引数、状態、インラインのデフォルト値を参照しないでください。
• プロバイダーが手動で貼り付けるトークンにも対応している場合は、OAuth メソッドの後に type: source_config のフォールバックを含めます。プロバイダーのトークンエンドポイントでクライアントシークレットによるクライアント認証が必要な場合は、OAuth クライアント値を両方とも入力してもらいます。client.id.input、client.secret.input、client.secret.transport（basic_auth または request_body）を宣言してください。
• OAuth クライアント認証情報だけを目的として、トップレベルのソース入力を追加しないでください。client.id.input と client.secret.input は OAuth のセットアップ時に収集されます。
• kind: identity マニフェストでは、プロバイダーの issuer、アイデンティティの type、セットアップ入力、OAuth URL、クライアント ID、クライアントシークレットをアイデンティティ仕様自体に記述します。アイデンティティ OAuth の client.id には、default、変数の input、またはその両方を指定できます。client.secret.input は宣言済みのシークレット入力を参照する必要があります。OAuth URL テンプレートが参照できるのは、宣言済みの変数入力のみです。アイデンティティ入力では、ソース認証方法を宣言しないでください。
• 各認証方法では、任意の label、description、hint フィールドを使用できます。これらは対話型インストール時と生成されたソースドキュメントに表示されます。入力に複数の認証方法がある場合は、長い入力レベルの hint に取得方法をまとめるのではなく、各方法が収集するフィールドの横に表示されるよう、各方法の hint に取得方法を記述してください。それぞれのヒントの対象は、その方法が収集する入力に限定してください。
• OAuth アクセストークンの有効期間が短い場合は、プロバイダーが対応していれば、認可コードまたはデバイスコードの方法でリフレッシュトークンを取得できるようにします。また、リフレッシュトークンの発行に必要なスコープ、同意プロンプト、クライアント設定を記載してください。プロバイダーから利用可能な expires_in メタデータが返される場合、クライアントクレデンシャル方式では保存済みのクライアントメタデータからアクセストークンを再発行します。これがない場合、トークンの有効期限が切れた後にユーザーは再接続する必要があります。別の OAuth 方式でリフレッシュトークンが発行されない場合、ソースに別の対応済みの長期間有効な認証情報経路がない限り、アクセストークンの有効期限が切れるとユーザーは再接続が必要であることを明記してください。
• テーブル名とテーブル関数名は安定性があり、SQL で扱いやすく、ソースの大文字小文字を区別しないリレーション名前空間内で一意になるようにします。テーブル名には snake_case の単純な名前を優先します。テーブル関数名は ASCII 英字またはアンダースコアで始め、その後は ASCII 英字、数字、アンダースコアのみを使用する必要があります。
• API が実際に必須とする場合に限り、フィルターを必須として指定します。
• スコープ付きの子コレクション、期間を指定したログ、メトリクスのクエリ、安定したテーブルに適切に対応付けられない詳細取得など、パラメーター付きの取得以外の操作には、デフォルトのテーブル関数を使用します。
• クエリテキストを受け取り、順位付けされた候補を返すプロバイダーのエンドポイントには、kind: search のテーブル関数を使用します。
• プロバイダーの引数が文字列型ではない場合は、テーブル関数の引数に type を設定します。引数の型を省略すると、デフォルトで Utf8 になります。
• プロバイダーの検索をテーブルフィルターとしてモデル化しないでください。通常のプロバイダー側部分文字列フィルターに限り、mode: contains を使用します。プロバイダーによる順位付けを伴う取得には、kind: search 関数を使用します。
• すべての kind: search 関数に search_limits を含め、後続の詳細クエリで使える安定した結果 ID を公開します。
• API の形式が分かっている場合は、明示的なページネーションを優先します。
• COUNT(*) だけでなく、実際に行を取得してページネーションを検証します。
• coral source test で基本的なスモークテストまたは接続チェックを実行する場合は、test_queries を追加または更新します。

メタデータの UX ルール

トップレベルのソースメタデータには、ソースの発見とセットアップに一貫性を持たせるため、以下のルールを使用してください。

description

• Query ... で始めてください。
• 最初の文では、クエリ可能な主要なエンティティを列挙し、機能を優先して説明してください。
• 推奨テンプレート：
  • Query <entities> from <Provider> (<Cloud or self-hosted when relevant>).
• description はデータの対象範囲に焦点を当て、セットアップ手順は記載しないでください。
• 次のような曖昧な表現は使用しないでください。
  • REST API v3
  • OpenAPI provider
  • ... and more
• 認証、セットアップ、権限の詳細は、description ではなく入力ヒントに記載してください。

入力ヒント（inputs.<KEY>.hint）

各ヒントでは、ユーザーに次のことを伝えてください。

• どのような値が必要か
• その値の取得方法
• 必要最小限のスコープや権限に関するガイダンス
• 必要に応じて、具体的な形式や例を1つ

具体的なガイダンス：

• URL／ベース URL 入力の場合：
  • デフォルトが何を意味するかを説明してください
  • 具体例を少なくとも1つ含めてください
  • 対応している場合はセルフホストに関するガイダンスも含めてください
• シークレットの場合：
  • 正確な認証情報の種類（API キー、PAT、アプリケーションキーなど）を明記してください
  • 関連する場合は形式上の制約（トークンの接頭辞など）を含めてください
  • 最小権限のスコープに関するガイダンスを含めてください
• OAuth メソッドの場合：
  • Connect with GitHub のような、ユーザーに表示する label を使用してください
  • description は短い1行の説明にとどめ、セットアップの詳細はメソッドの hint に記載してください
  • メソッドの hint には、必要な OAuth スコープを列挙してください。また、固定のループバックリダイレクト URI を登録する必要があるのか、ユーザー自身の OAuth クライアント ID／シークレットを指定する必要があるのかを説明してください。メソッドが client.id.input／client.secret.input を収集する場合は、それらの値の取得先を記載してください
  • 認可コードフローでは、ブラウザーから Coral のループバックリスナーに直接アクセスできない場合、localhost の最終リダイレクト URL をターミナルに貼り付けられることを、メソッドの hint に記載してください
  • シークレットで複数のメソッドを選択できる場合は、すべてのメソッドに関するガイダンスをまとめた広範な入力レベルのヒントを1つ書くのではなく、各メソッドが収集する入力に合わせて hint の内容を分けてください
• 派生シークレット（Basic 認証用の文字列など）の場合：
  • 短いシェルの例（Base64 コマンドなど）を含めてください
• 安定したドキュメントリンクを優先してください。
  • 公式ドキュメントへのリンクと、安定した設定ページを使用してください。
  • クリック経路に依存する手順は、主なガイダンスとして使用しないでください。

ヒントは簡潔で、すぐに実行できる内容にしてください。

検証ループ

作成時には、次のループを使用してください。

# Export any required inputs first (key matches the input `key` in the spec),
# or pass --interactive to be prompted.
coral source lint ./my-source.yaml
coral source add --file ./my-source.yaml
coral source test my_source
coral sql "SELECT catalog_name, schema_name, table_name, description, required_filters FROM coral.tables WHERE schema_name = 'my_source' OR catalog_name = 'my_source' ORDER BY catalog_name, schema_name, table_name LIMIT 50 OFFSET 0"
coral sql "SELECT function_name, kind, arguments_json, result_columns_json, search_limits_json FROM coral.table_functions WHERE schema_name = 'my_source' ORDER BY function_name LIMIT 50 OFFSET 0"
coral sql "SELECT table_name, filter_name, filter_mode, is_required, data_type, description FROM coral.filters WHERE schema_name = 'my_source' OR catalog_name = 'my_source' ORDER BY table_name, filter_name LIMIT 100 OFFSET 0"
coral sql "SELECT table_name, column_name, data_type, is_virtual, is_required_filter, filter_mode, description FROM coral.columns WHERE schema_name = 'my_source' OR catalog_name = 'my_source' ORDER BY table_name, ordinal_position LIMIT 100 OFFSET 0"
coral sql "SELECT catalog_name, key, kind, value, default_value, hint, required, is_set FROM coral.inputs WHERE schema_name = 'my_source' OR catalog_name = 'my_source' ORDER BY key"

各 WHERE 句は両方の修飾子を条件にします。ソースはスキーマまたはカタログのいずれかで指定されるためです。スキーマで指定されたソースは schema_name にソース名を持ち、catalog_name は空です。データベースソースは catalog_name にソース名を持ち、その coral.inputs 行では schema_name が空です。schema_name のみでフィルタリングすると、データベースソースではエラーが報告されずに0行が返され、「このソースは何も宣言していない」という結果になります。

リポジトリのソース、またはすでに名前が付いているソースには、基本的なスモークテスト／接続確認用の test_queries を追加して、次を実行してください。

coral source test my_source

その後、ソースが正しく動作するまで、対象を絞ったテーブルクエリを実行してください。

HTTP ソース

HTTP をバックエンドとするソースの場合：

• backend: http を定義します
• base_url を定義します
• 認証ヘッダーまたはその他の実行時認証フィールドを定義します
• セットアップ時に OAuth などの取得方法を選択できるようにする場合は、シークレット入力に credential.methods を定義します
• 必要な場合にのみ、リクエストのパス、クエリ、本文を定義します
• 呼び出し引数が必要なプロバイダー固有の操作には、ソーススコープのテーブル関数を定義します
• レスポンスの rows_path を定義します
• プロバイダーのパターンがわかっている場合は、ページネーションを明示的に定義します
• 型付きカラムを定義します
• ソースが基本的に動作することを確認する簡単なクエリがわかったら、test_queries を追加します

テーブルの形状やページネーションに関するガイダンスが必要な場合は、references/http-source-checklist.md を参照してください。

HTTP ソースでプレフィックス付きの Authorization ヘッダー（例：Authorization: Bearer <token>）を使用する場合は、未加工のトークン用にシークレット入力を使用し、ヘッダーを from: bearer で定義します。

inputs:
  FOOBAR_API_TOKEN:
    kind: secret
    hint: Bearer token for the Foobar API.
auth:
  type: HeaderAuth
  headers:
    - name: Authorization
      from: bearer
      key: FOOBAR_API_TOKEN

OAuth 対応の HTTP ソースの場合は、同じシークレット入力に取得方法を追加します。

inputs:
  FOOBAR_API_TOKEN:
    kind: secret
    hint: Connect with Foobar OAuth or paste a token with read access.
    credential:
      methods:
        - type: oauth
          label: Connect with Foobar
          description: Open a browser and authorize Coral to read Foobar data.
          hint: |
            Signs you in through Foobar and requests the `read` scope. To
            use your own app, set FOOBAR_OAUTH_CLIENT_ID to its Client ID.
          oauth:
            flow:
              type: authorization_code
              pkce: required
            redirect_uri: http://127.0.0.1:0/oauth/callback
            redirect_uri_port_mode: random
            endpoints:
              authorization_url: https://foobar.example.com/oauth/authorize
              token_url: https://foobar.example.com/oauth/token
            client:
              id:
                input: FOOBAR_OAUTH_CLIENT_ID
            scopes:
              scope:
                delimiter: space
                values:
                  - read
        - type: source_config
          label: Paste token
          hint: Paste a Foobar API token with read access to the data you query.
auth:
  type: HeaderAuth
  headers:
    - name: Authorization
      from: bearer
      key: FOOBAR_API_TOKEN

プロバイダーが、貼り付けた完全な API キーヘッダーと OAuth アクセストークンのどちらも受け付ける場合は、両方の認証情報入力をオプションのシークレットとして宣言します。そのうえで from: one_of を使用し、完全なヘッダー値を先に指定し、その後に from: bearer による OAuth フォールバックを指定します。

inputs:
  FOOBAR_API_KEY:
    kind: secret
    required: false
  FOOBAR_OAUTH_ACCESS_TOKEN:
    kind: secret
    required: false
auth:
  type: HeaderAuth
  headers:
    - name: Authorization
      from: one_of
      values:
        - from: input
          key: FOOBAR_API_KEY
        - from: bearer
          key: FOOBAR_OAUTH_ACCESS_TOKEN

ローカルデータソース

ローカルファイルをバックエンドとするソースの場合：

• ファイルバックエンドを定義します
• ソースの場所を定義します
• 該当する場合はファイル選択パターンを定義します
• 型付きカラムを定義します

成果物

以下を報告します。

• ソース仕様のパス
• 使用した lint／add／test コマンド
• 実行した検証コマンド
• 行った仮定
• ブロックされている、または未検証のエンドポイント