package-spec

package-spec

スキルの権威性

このスキルとその参照ファイルで定義されているルールとパターンが、権威ある唯一の情報源です。参照用に elastic/integrations リポジトリ内の既存の統合を調べると、ここで指定されている内容と矛盾するパターンに遭遇することがあります。多くの統合には、現行の標準より前のレガシーパターンが含まれています。**必ず、他の統合で見られるパターンよりもこのスキルに従ってください。**参照用の統合で非推奨または禁止されているパターンが使われている場合、それをコピーしないでください。

使用する場面

次の作業では、このスキルを使用します。

• ルートまたはデータストリームレベルで manifest.yml を作成またはレビューする
• changelog.yml のエントリを追加または検証する
• 適切な変更タイプとセマンティックバージョンの更新を選択する
• ポリシーテンプレート、入力、変数宣言を設定する
• var_groups または provider_permissions（スキーマと下限）を宣言する
• マニフェストまたは変更履歴に関する elastic-package lint または elastic-package check のエラーをデバッグする
• パッケージ、ポリシーテンプレート、入力、データストリーム各レベル間の変数スコープをレビューする
• Handlebars テンプレートの変数がマニフェストの宣言と一致することを検証する
• ルーティングルールと、それに必要なマニフェストフラグを設定する
• パッケージの機能に必要な format_version を判断する

使用しない場面

• パッケージのひな型作成とディレクトリ構成（create-integration）
• AWS パッケージでの Federated Identity／Cloud Connectors のエンドツーエンドの有効化（input-configurations -> references/federated-identity-aws.md）
• Ingest パイプラインの設計（ingest-pipelines）
• フィールドマッピングと ECS 準拠（ecs-field-mappings）
• CEL プログラム（cel-programs）
• Transform の設定（review-integration スキルの references/transform-guide.md を参照）

引き継ぎ

パッケージのディレクトリ構成と必須ファイルについては、create-integration -> references/package-layout.md を参照してください。elastic-package の CLI コマンドとトラブルシューティングについては、elastic-package-cli を参照してください。AWS 統合で Federated Identity（Cloud Connectors）を有効にする方法については、input-configurations -> references/federated-identity-aws.md を参照してください。

---

format_version

manifest.yml の format_version フィールドは、パッケージが準拠する elastic/package-spec のバージョンを宣言します。新しいパッケージの現在のデフォルトは "3.4.2" です。

パッケージが実際に使用する機能をサポートする最小バージョンを使用してください。利用可能な最新の仕様バージョンではありません。新機能が必要ないのにバージョンを引き上げると、次の問題が発生します。

• 不必要に新しい Kibana をユーザーに要求する
• 理由もなく後方互換性を損なう
• パッケージが依存する機能を特定しにくくする

パッケージが新しい仕様バージョンで導入された機能を使用する場合にのみ、バージョンを引き上げてください。

機能	最小の format_version
基本的なパッケージ構造	1.0.0
入力レベルの変数	2.0.0
elasticsearch.privileges	2.3.0
routing_rules.yml のサポート	2.9.0
lifecycle フィールド	3.0.0
シークレット変数（secret: true）	3.0.0
elasticsearch.source_mode	3.0.3
var_groups	3.6.1
provider_permissions（Federated Identity IAM 宣言）	3.6.4

妥当な例外 — Federated Identity：provider_permissions（通常は var_groups も）を宣言するパッケージでは、format_version: "3.6.4" を使用する必要があります。このバージョンへの引き上げにより、3.6.0 以降のパイプラインバリデーターが有効になります。lint によって既存の違反が明らかになった場合は、まずパイプラインの整理を完了してください。references/var-groups-and-provider-permissions.md と input-configurations -> references/federated-identity-aws.md を参照してください。

最近追加された仕様（3.6.0 以降）を含む、機能とバージョンの完全な対応表については references/format-version-features.md を、レビュー手順については references/manifest-rules.md を参照してください。

---

conditions.kibana.version

現在のデフォルトの制約は "^8.19.0 || ^9.1.0" です。これはルートの manifest.yml でのみ設定してください。データストリームのマニフェストで独自の conditions を設定してはいけません。

統合で、より新しいエージェントを必要とする機能（例：v9.3.0 で導入された CEL 関数）を使用する場合は、それに応じて制約を調整する必要があります。CEL 機能のバージョンを体系的に確認する方法については、review-integration スキルのバージョンチェックに関するリファレンスを参照してください。

正当な例外 — Federated Identity／use_cloud_connectors： conditions.kibana.version を "^9.6.0" に、conditions.agent.version を "^9.4.0"（またはそれ以上）に設定してください。現在の Kibana 制約が、^9.6.0 にすると対象外になる系列をまだカバーしている場合は、Floors and hygiene に従って input-configurations -> references/federated-identity-aws.md で対応をエスカレーションしてください。黙って引き上げてはいけません。

---

変数のスコープ

Fleet の変数には 4 つのレベルがあります。

1. パッケージレベル -- manifest.yml のトップレベルにある vars:
2. ポリシーテンプレートレベル -- manifest.yml の policy_templates[].vars: の下
3. 入力レベル -- manifest.yml の policy_templates[].inputs[].vars: の下
4. データストリームレベル -- data_stream/*/manifest.yml の streams[].vars: の下

内側のスコープで宣言する変数に、外側のスコープの変数と同じ名前を使用してはいけません。これは変数のシャドーイングと呼ばれ、elastic-package の検証で拒否されます。

詳細なルール、例、一般的なパターンについては、references/manifest-rules.md -> Variable shadowing を参照してください。

---

マニフェストのルール（概要）

• すべての Handlebars {{var}} はマニフェストで宣言する必要があります -- 宣言されていない変数は、エラーにならず空文字列として解決されます。Handlebars ヘルパー（{{#if}}、{{#each}}、{{#unless}}、{{#contains}}）と組み込み変数（{{data_stream.type}}、{{data_stream.dataset}}、{{data_stream.namespace}}、{{output}}）は対象外です。

• ルーティングルールには動的フラグが必要です -- データストリームが routing_rules.yml を使用する場合、データストリームのマニフェストで elasticsearch.dynamic_dataset: true と elasticsearch.dynamic_namespace: true を宣言する必要があります。

• ドット区切りのキーではなく、適切な YAML のネスト構造を使用してください -- elasticsearch.dynamic_dataset をリテラルなキー名として指定すると、ネストされたオブジェクトではなく、単一のフラットなキーが作成されます。elasticsearch: -> dynamic_dataset: のようにネストした構造を使用してください。

• Lint が成功しても、入力の存在が証明されるわけではありません -- 入力の名前は、出現するすべての箇所で検証されない文字列です。統合パッケージでは policy_templates[].inputs[].type とデータストリームの streams[].input、入力パッケージでは policy_templates[].input が該当します。統合パッケージでこれとは別のフィールドとして使われる、列挙型に基づくデータストリームの type と混同しないでください。references/manifest-rules.md -> Input names are not validated を参照してください。

完全なルール、正しい例と誤った例、レビュー用チェックリストについては、references/manifest-rules.md を参照してください。

---

変更履歴のスキーマ

changelog.yml はバージョンごとにまとめられた配列です。新しいバージョンを先頭に記載してください。

- version: "1.2.0"
  changes:
    - description: Added example parsing for edge-case payloads.
      type: enhancement
      link: https://github.com/elastic/integrations/pull/12345

各エントリーには description、type、link が必要です。有効なタイプは enhancement、bugfix、breaking-change です。

バージョン引き上げのルール

• パッチ（x.y.Z）：バグ修正とリスクの低い修正
• マイナー（x.Y.z）：新しいコンテンツ（新しいデータストリーム、新しいフィールド、新機能）
• メジャー（X.y.z）：破壊的変更（既存の統合におけるフィールド型の変更や削除、ECS マッピングの競合、既存のポリシーに影響する必須の設定／認証の変更、データストリームの再構成、収集データや正規化データを変えるデフォルト動作の変更）

バンプが不要な場合

ユーザーに提供される内容を変更しない内部メタデータのみの変更には、バージョンのバンプも変更履歴への記載も必要ありません。対象は、owner.github の再割り当て、CODEOWNERS の更新、ビルド済みパッケージの外部にある CI／開発ツール関連ファイルです。レビュー担当者は、このような差分に対してバンプがないことを指摘してはいけません。

elastic/integrations の慣例に基づく関連するバンプ規則については、日付入りの詳細を review-integration/references/repo-conventions.md で確認してください。

• owner.type の変更は公開パッケージのメタデータにあたるため、マイナーバンプが必要です。
• マニフェストのトップレベルに group: フィールドを追加する場合は、パッチバンプと変更履歴への記載が必要です。
• ボットが作成した requires: の依存関係のバンプには、独自のパッチバンプと変更履歴への記載が含まれています。人間にやり直しや正当化を求めてはいけません。
• kibana.version の制約更新は、破壊的変更ではありません。

変更履歴の type の調整（レビュー担当者向け）

差分またはエントリー自体の説明から、互換性や動作に観察可能な変更が確認できる場合に限り、エントリーの type を指摘してください。対象は、スタックのサポート終了、データセット／フィールドの名前変更または削除、フィールド型の変更、デフォルト動作の変更、ポリシーに反する設定の移動です。bugfix と enhancement の間で分類し直すことや、エントリーを分割・統合することは、作成者の編集上の判断であり、レビューで指摘する事項ではありません。

変更履歴エントリーの追加

changelog.yml を直接編集するか、elastic-package changelog add を使用してください（コマンドフラグと --next patch|minor|major の使い方については elastic-package-cli スキルを参照してください）。

よくある変更履歴の落とし穴

• 間違ったバージョンの下、または先頭以外にエントリーを追加する
• link フィールドがない、または誤っている。リンクには、変更を導入するプルリクエストの URL（https://github.com/elastic/integrations/pull/<n>）を指定する必要があり、issue の URL ではありません。elastic-package lint は数値が正の整数かどうかのみを検証し、pull/0 は拒否します。実際の PR 番号を使うか、開発時のプレースホルダーとして pull/99999 を使用し、マージ前に置き換えてください。レビューツールはプレースホルダー形式（1 や 9999 などの同じ数字の繰り返し、ゼロ、99999、12345）を認識し、PR 自身の番号以外はすべて CI で失敗するため、置き換えるまではプレースホルダーが引き続き指摘されます。これはマージ前の想定された動作であり、ノイズではありません
• マニフェスト／パッケージのバージョンを、変更履歴の意図と合わない形でバンプする
• プレースホルダーリンクを実際のリンクに戻し忘れる――以下を参照してください

詳細なパターン、破壊的変更のチェックリスト、CI の例については、references/changelog-patterns.md を参照してください。

PR 作成後の変更履歴リンクの更新

変更履歴の link フィールドには変更を導入する PR を指定する必要がありますが、 実際の PR 番号がわかるのは PR を実際に作成してからです。そのため、それまでは 上記の落とし穴にある pull/99999 のプレースホルダーを使う必要があります。この 手順は、パッケージ作業を終えた後に、通常のビルド／テストの流れの外で行うため、 抜け落ちやすいものです。

GitHub で PR を作成したら、次の手順を実行してください。

1. 実際の PR 番号を取得します（gh pr create の出力または PR の URL から取得できます）。
2. changelog.yml で、すべてのプレースホルダーリンク （https://github.com/elastic/integrations/pull/99999）を https://github.com/elastic/integrations/pull/<real-number> に置き換えます。
3. elastic-package lint を実行し、リンクが検証に合格することを確認します。
4. 更新を同じ PR ブランチにコミットしてプッシュします。マージされるバージョンに プレースホルダーが残っていてはいけません。

---

上流：elastic/package-spec

elastic/package-spec リポジトリは、パッケージの構造、マニフェストのスキーマ、検証ルールの上流の権威です。このリポジトリの spec/changelog.yml には、各仕様バージョンで追加された機能が記載されています。

package-spec のバージョニングモデルの要点：

• パッケージでは、ルートの manifest.yml に format_version を指定する必要があります
• format_version: x.y.z のパッケージは、[x.y.z, X.0.0) の範囲の仕様に照らして有効である必要があります（X = x + 1）
• パッチバージョンでは、より厳格な検証が追加される場合があります（例：3.6.0 では、パイプラインタグと on_failure の検証が追加されました）
• マイナーバージョンでは、新しい機能のサポートが追加されます
• メジャーバージョンは、大幅なフォーマット変更のために設けられています

機能とバージョンの対応表については、厳選された references/format-version-features.md を参照してください。

参照ファイル

ファイル	内容
references/manifest-rules.md	format_version の選択、変数のシャドーイング、Handlebars 変数宣言、ルーティングルール、YAML 構造、重大度タグ付きレビュー用チェックリストに関するすべてのルール
references/changelog-patterns.md	変更履歴エントリーのパターン、semver ルール、破壊的変更のチェックリスト、CI の例
references/format-version-features.md	elastic/package-spec を出典とする機能とバージョンの対応表（最近追加された仕様も含む）
references/var-groups-and-provider-permissions.md	var_groups と provider_permissions のスキーマ、下限、バリデーター、および Federated Identity の手順への引き継ぎ