Plugin マニフェスト

すべての plugin は、ソースコードと同じ場所に manifest.json を同梱します。マニフェストでは、plugin のメタデータ、plugin が必要とする Databricks リソース、そして databricks apps init の実行時にスキャフォールディングエージェントが従うべき構造化されたルールを宣言します。マニフェストは次の 3 つの段階で使用されます。

• 作成時 — import manifest from "./manifest.json" で読み込み、static manifest を使って Plugin サブクラスに設定します。
• 同期時 — appkit plugin sync --write が、インストール済みパッケージとローカル plugin のマニフェストを集約し、appkit.plugins.json にまとめます。
• 初期化時 — databricks apps init が appkit.plugins.json を読み取り、plugin の選択、リソースに関する入力、.env / databricks.yml / app.yaml の生成を行います。

このページでは v2.0 のマニフェスト仕様について説明します。JSON Schema は https://databricks.github.io/appkit/schemas/plugin-manifest.schema.json で公開されています。エディタでの validation には $schema で参照してください。

推奨パターン

マニフェストを JSON で記述し、plugin モジュールにインポートして、型をアサートします。

// packages/my-plugin/src/index.ts
import { Plugin, toPlugin } from "@databricks/appkit";
import type { PluginManifest } from "@databricks/appkit";
import manifest from "./manifest.json";

class MyPlugin extends Plugin {
  static manifest = manifest as PluginManifest<"my-plugin">;
  // ...
}

export const myPlugin = toPlugin(MyPlugin);

// packages/my-plugin/src/manifest.json
{
  "$schema": "https://databricks.github.io/appkit/schemas/plugin-manifest.schema.json",
  "name": "my-plugin",
  "displayName": "My Plugin",
  "description": "A custom plugin",
  "resources": {
    "required": [],
    "optional": []
  }
}

JSONが正規の記述形式であり、appkit plugin sync が読み込むのもこのJSONです。JS形式のマニフェスト (manifest.js / manifest.cjs) は既定では無視され、使用するには --allow-js-manifest を明示的に指定する必要があります (pluginのコードが実行されるため、信頼できるものに限ります) 。CLIのエンドツーエンドの動作については、Plugin managementを参照してください。

必須フィールド

Resources

リソース要件は、pluginが依存するDatabricksリソースを1つ宣言します。その構造は type をキーとして決まり、type ごとに有効な permission の値が定まります (スキーマ上は判別可能なユニオンとして検証されます) 。

どの要件にも、次の項目があります。

• alias — UI / CLI のoutputに表示される、人が読めるラベル。
• resourceKey — 変更されないマシン向けキー ([a-z][a-z0-9-]*) 。重複排除、環境変数名の生成、app.yaml 内での参照に使われます。識別に使われるのは alias ではなく resourceKey です。
• description — そのリソースがなぜ必要かの説明。対話的なpromptに表示されます。
• fields — フィールド名 → フィールドエントリのマップ (後述) 。指定する場合は最低1エントリが必要です。
• permission — その type で許可された列挙値のいずれかと一致している必要があります。

単一値のリソース type (例: sql_warehouse) は通常、フィールドを1つ (id) だけ宣言します。複数値の type (例: secret、database) は複数のフィールド (scope + key、instance_name + database_name) を宣言します。

フィールドエントリ

{
  "id": {
    "env": "DATABRICKS_WAREHOUSE_ID",
    "description": "SQL Warehouse ID",
    "examples": ["1234abcd5678efgh"],
    "discovery": { "type": "kind", "resourceKind": "warehouse" }
  }
}

設定に依存するリソース

マニフェストでは、静的解析のために required と optional を区別します。pluginのランタイム設定によって初めて必須になるリソースは、マニフェストには optional として記載し、pluginクラスの静的メソッド getResourceRequirements(config) でruntimeに上書きしてください。詳細はカスタムpluginの作成を参照してください。

リソースのディスカバリー

ディスカバリー (discovery) は、対話型 init の実行中に CLI がフィールドの候補値をどのように提示するかを定義します。discovery には、type によって区別される 2 種類のバリアントがあります。

kind バリアント (推奨)

{
  "discovery": {
    "type": "kind",
    "resourceKind": "warehouse"
  }
}

kind バリアントは、AppKit が一覧取得コマンドとレスポンス形状を管理する既知の Databricks リソース種別を参照します。first-party の Databricks リソースにはこの形式が推奨されます。plugin の作者は何を一覧するかを宣言し、どのように一覧するかは AppKit が引き受けます。

サポートされる resourceKind の値:

kind バリアントでサポートされるオプション:

cli バリアント (エスケープハッチ)

kind マップにないリソースの場合は、cli バリアントにフォールバックします。

{
  "discovery": {
    "type": "cli",
    "cliCommand": "databricks custom-resource list --profile <PROFILE> --output json",
    "selectField": ".id",
    "displayField": ".name"
  }
}

cli バリアントは意図的に最小限の設計としており、将来のバージョンでより厳格になる可能性があります。AppKit が把握しているリソースについては、kind バリアントを優先してください。コマンドとアンラップ規則について単一の信頼できる情報源が得られ、AppKit がディスカバリー契約を改良していく中でも前方互換性が保証されます。

フィールドの依存関係

あるリソースの一覧取得が別のリソースに依存する場合 (たとえば、ボリュームの一覧取得にはカタログとスキーマが必要、Postgres branch の一覧取得には project が必要) 、dependsOn で順序を宣言します。

{
  "fields": {
    "project": {
      "discovery": { "type": "kind", "resourceKind": "postgres_project", "select": "name" }
    },
    "branch": {
      "discovery": {
        "type": "kind",
        "resourceKind": "postgres_branch",
        "select": "name",
        "dependsOn": "project"
      }
    }
  }
}

dependsOn は、同じリソース内の兄弟フィールド名を参照します。CLI は依存関係の順序でプロンプトを表示し、解決された値を親コマンドに埋め込みます (例: databricks postgres list-branches {project} の {project}) 。

スキーマはパース時に依存関係グラフを検証します:

• 無効な参照 (存在しない兄弟フィールドを指す dependsOn) は拒否されます。
• 循環参照は、その連鎖 (a → b → a) を示したうえで拒否されます。

一時的な prompt (parents)

kind のバリアントコマンドの中には、リソースの兄弟フィールドではない値を必要とするものがあります。これらは、ランナー が一度だけ収集してそのまま破棄する query の入力です。AppKit では、RESOURCE_KIND_COMMANDS の parents 配列によって、これらを kind 自体に宣言します。

現時点で parents を使用する kind は volume のみです:

databricks volumes list {catalog} {schema} --profile <PROFILE> --output json を実行する前に、ランナーは parents の各エントリについてユーザーに自由入力を求め、入力された値を対応する {name} プレースホルダーに差し込みます。dependsOn とは異なり、ここで収集した値はリソースのフィールドとして永続化されません。一覧取得の呼び出しの間だけ存在する値です。

plugin の作成者がマニフェストで parents を宣言することはありません。これは AppKit が所有する kind コントラクトの一部であり、各 kind のコマンドテンプレートとともに公開 JSON Schema に現れます。

スキャフォールディングのルール

scaffolding.rules は、スキャフォールディングを行うエージェント (LLM 駆動のランナー、独自の CLI workflows、databricks-apps スキル) に渡す plugin レベルの指示です。must、should、never という最大 3 つの短いディレクティブのリストを持ち、この plugin を選択した状態で databricks apps init を実行する際に、エージェントはこれらに従います。

{
  "scaffolding": {
    "rules": {
      "should": [
        "After init, run any database migrations for your chosen ORM before first request",
        "After init, verify Lakebase connectivity with 'psql $PGHOST -c \"select 1\"'"
      ]
    }
  }
}

記述ルール

• 各エントリは短い指示を1つだけ記述し、スキーマ上120文字までに制限されています。長い文章は validation に失敗するため、実行可能な単位に分割してください。
• スキーマはバケット内の重複排除 (must / should / never のいずれか1つの中に同じテキストのエントリを2つ置けない) とバケット間の重複排除 (1つのエントリが同時に2つのバケットに属せない) の両方を強制します。
• 順序が重要な場合は Before init / After init という接頭辞の規約に従い、利用側が指示を一貫した順序で処理できるようにしてください。

代替可能性ゲート

ルールをマニフェストに記述してよいのは、他の場所で構造化データとして表現できない場合のみです。ここでいう他の場所とは、リソースの権限、discovery ディスクリプタ、dependsOn チェーン、requiredByTemplate フラグ、config フィールド、あるいはフィールドの env / value / resolve スロットなどを指します。

ゲートを通過する例:

• "After init, run any database migrations for your chosen ORM before first request" — runtime の実行順序に関する内容であり、どのリソース定義からも導出できません。
• "After init, configure the 'spaces' map in plugin config with alias-to-Space-ID mappings" — スキーマでは表現できない config 設定のガイダンスです。

ゲートを通過しない例 (代わりにモデル化すべきもの) :

• 「Plugin X はその volume に対して READ_VOLUME を必要とする」→ リソースの permission フィールドにすでにエンコードされています。
• 「project が選択された後、ランナーは Postgres の branch を一覧表示しなければならない」→ dependsOn によってすでにエンコードされています。
• 「volume を一覧表示する前に、ユーザーに catalog と schema を尋ねる」→ RESOURCE_KIND_COMMANDS.volume.parents によってすでにエンコードされています。

スキーマで表現できる内容を文章で書こうとしていることに気づいたら、代わりにスキーマを拡張してください。

rules ブロックは、plugin マニフェストから同期先のテンプレートマニフェストへそのまま引き継がれます。CLI が plugin レベルのルールと template レベルの rules ブロックをどのようにマージするかは、Templates — scaffolding.rules の伝播 を参照してください。

任意フィールド

関連項目

• カスタム plugin の作成 — plugin をゼロから構築する方法。
• Plugin の管理 — appkit plugin sync、create、validate、add-resource。
• Templates — 同期されたテンプレートマニフェストが databricks apps init の動作をどのように制御するか。
• PluginManifest API リファレンス — TypeScript の型定義。