検証の対象範囲
Aggrega は、作成されたコンテンツを 4 つの異なるスキーマ層にわたって検証します。各層は異なる範囲を対象とし、コンパイルパイプラインの異なる時点で実行され、異なる形式のエラーを生成します。検証エラーに遭遇した作成者は、どの層が入力を拒否したかを知っておくと役立ちます。同じフィールドが複数の層によって管理される場合があり、どの層が発火したかによって、何をどこで修正すべきかが決まるためです。
このページでは、4 つの層、それぞれのパイプライン上の位置、各層が従うエラー形式の慣例、そして同じフィールドに複数の層が適用される場合の層同士の相互作用について説明します。
4 つのレイヤー
レイヤー 1 — JSON Schema エンベロープ
対象範囲。 すべてのカタログ YAML の構造的な形状です。apiVersion、kind、metadata.{name, version, description, maintainers, license, ...}、トップレベルの spec: ブロック、およびスキーマが宣言するエンティティごとの必須フィールドが含まれます。各エンティティ種別(Aggregate、Component、Feature、Recipe、FeatureRecipe、Manifest、Plugin、Release、SchemaLibrary、MappingLibrary、WorkloadLibrary、ArtifactLibrary)は独自の JSON Schema を持ち、スキーマリファレンスに記載されています。Workload もそこにスキーマを持ちますが、この中で唯一、独立したカタログファイルとしてではなく、別のエンティティの内部(Recipe または FeatureRecipe の workload: ブロック、あるいは WorkloadLibrary のエントリ)に記述される種別です。どこに記述されても同じエンベロープチェックが適用され、aggrega validate は Workload ファイルを単一エンティティの対象として直接受け付けます。
検証の実行時点。 解決時(resolver / load)に、ファイルごとに実行されます。各ドキュメントは読み込み時にその種別の JSON Schema に対してチェックされ、スキーマが宣言するフィールド以外のキーは、以降の検証が実行される前にその時点で拒否されます。
エラーの形状。 スキーマの不一致は、ドキュメントエンベロープの失敗として報告されます。その先頭には問題のあるドキュメントのカテゴリが付きます。カタログエンティティでは [CATALOG_ERROR E0215]、Aggregate では [DEVELOPER_ERROR E0215]、Release では [OPS_ERROR E0215] です。メッセージには種別、ファイル、行と列、フィールドパス、違反した制約が示されます:
[CATALOG_ERROR E0215] <path> document envelope validation failed (Recipe, at <path>); 11:3: spec.foo: unexpected property: "foo". correct the document to match its kind's schema必須フィールドの欠落や型の不一致も同じ形状で表面化します — spec.capability: missing required property: capability、metadata.version: type: 1 has type "integer", want "string"。
レイヤー 2 — ピラースキーマ(schema: / featuresSchema / usesSchema)
対象範囲。 エンティティが持つデータピラー、すなわち values、infra、parameters に加え、スロットを featuresSchema が宣言する features: アタッチメントブロックと、usesSchema が管理する uses: ブロックです。ドメイン 2 のエンティティ(Component、Feature)は、YAML エンベロープに JSON Schema 2020-12 の宣言を埋め込みます(インラインの spec.schema(コンパクト形式または完全形式)、または共有 SchemaLibrary エントリへの $ref:)。ドメイン 3 のエンティティ(Recipe、FeatureRecipe)は、自身の検証パスの中で解決済みのスキーマを利用します。
検証の実行時点。 解決時に、JSON Schema エンベロープの検証を通過した後で実行されます。コンパイラは、エンティティに記述された schema: を、usesSchema と featuresSchema の宣言から自動生成されたベースと合成します。合成されたスキーマは、Aggregate 内のすべての component インスタンスについて、開発者が指定した values: / infra: / features: / uses: ブロックを検証します。
エラーの形状。 制約違反は、エンティティ、ピラー内のパス、および値を拒否したルールを示すメッセージとして表面化します。たとえば、>=1024 を要求するスキーマルールに対して、開発者がポートを 80 に設定した場合です。
usesSchema または featuresSchema のエントリを再宣言しても、合成の失敗は発生しません。この 2 つは名前によって上書きされます。子のエントリはベースのエントリをスキーマとセレクタごと完全に置き換えるため、ベースと子のエントリの間に報告すべき競合は存在しません。
レイヤー 3 — Provider の合成モード能力
対象範囲。 バインドされた provider の合成モード能力ゲートによって管理されます。
- 合成モード(
workload:)のサポートは、workloadSchemaの有無ではなく、バインドされた provider の能力によって判定されます。合成できない provider にバインドされたworkload:Recipe は、ここで拒否されます。標準ライブラリのカタログは、慣例により、合成可能な provider にworkloadSchemaを宣言します(provider をレンダリングする Plugin のspec.provider.workloadSchemaに)。これは文書化された変換契約です。そのworkloadSchema本体自体も Plugin のロード時に JSON Schema 2020-12 にコンパイルされます。これは構造的な受け入れゲートであり、不正な形式のスキーマをレンダリング時ではなくロード時に拒否します。
検証の実行時点。 ベースのレンダリング時に、Recipe 自身の valuesMapping が解決された後で実行されます。レイヤー 3 は、provider の能力に基づいて合成モードのディスパッチを判定します。
エラーの形状。 能力による拒否はカタログ作成ドメインに帰属するため、そのレポートは、そのカテゴリと問題のあるインスタンスを含む角括弧付きのヘッドで始まります。メッセージは条件を述べる固定の文で始まり、続いてノード、provider、およびその provider がサポートする種別を示します。
[CATALOG_ERROR] instance <node-id>: provider does not support the node's input kind (node "<node-id>"). provider "<provider-name>" does not support synthesized recipes (this provider supports: <kinds>); declare one of the supported input kinds, or target a provider that supports synthesized[CATALOG_ERROR] ヘッドは、開発者の Aggregate ではなくカタログエンティティに問題があることを示します。ターミナルでは、ヘッドに条件の短縮コード(この条件では E0265。すべての条件の表で参照できます)も含まれ、メッセージはインデントされた独立した行に移動します。上記の 1 行形式は、ログに出力される形式です。冒頭の文は条件ごとに固定されているため、テキストを基に照合する場合はこの部分を使います。それ以降の部分は、問題のあるノードによって変わります。
関連するガードレールが provider のディスパッチ自体を保護します。provider をレンダリングする Plugin が複数、同じターゲットを担当する場合、ワークスペースは .aggrega-config.yaml 内の provider バインディングによって曖昧さを解消します。このバインディングは aggrega pull の時点で選択され、ロックファイルに記録されます。バインディングがなく候補の Plugin が 1 つだけの場合は、その候補が使用されます。バインディングがなく候補が複数ある場合、ビルドは候補のプラグインを示して明示的に停止します。曖昧さは、カタログ全体の一意性ルールではなく、使用箇所でワークスペースごとに解消されます。
プロバイダーごとの Workload コンテンツ検証。 プロバイダーをレンダリングする Plugin の
spec.provider.workloadSchemaは、そのプロバイダーが Workload をどのように変換するかを記述し、そのプロバイダーが Workload を合成できることを示しますが、何も検証しません。すべての Workload の本体は、プロバイダーにかかわらず、プラットフォームの Workload スキーマに対して検証されます。
レイヤー 4 — アノテーションバインディングの値の検証
対象範囲。 Release の境界 / 境界 component、または Aggregate のサブシステム / component インスタンスに記述されたアノテーション値のうち、mappings.features.annotations.<key> 配下の Manifest バインディングが maps.infra と maps.values の一方または両方のドット区切りパスリストによるルーティングを宣言しているものです。宣言された各パスは、対象 Feature の spec.schema.<pillar> をたどってリーフプロパティに到達します。そのリーフへのアノテーション値の寄与は、Feature スキーマで宣言された型に対して検証されます。検証は Feature 自身の JSON Schema 2020-12 宣言を通じて行われます。バインディングが宣言するのはルーティングのみで、検証の断片は宣言しません。
検証の実行時点。 解決のアノテーション展開サブフェーズで、Manifest のバインディングターゲット検証(宣言された各パスが参照先の Feature スキーマに存在することを確認するカタログロード時のチェック)の後に、明示的なアタッチメントに対するレイヤー 2 のスキーマ検証と並行して実行されます。実効的な component ごとの各アノテーションについて、値をスカラー、構造化されたマップ、または明示的な null としてパースし、サイドとピラーの対応を強制しながら、バインディングのピラー別にグループ化された maps 宣言を通じてサブキーごとにルーティングし(Aggregate 側は maps.values を、Release 側は maps.infra を適用)、ルーティング先のピラーで Feature スキーマが宣言する型に対してリーフごとの実行時の値を検証します。複数のサブキーエラーは、停止する前にすべて収集して出力されます。
エラーの形状。 このレイヤーのスキーマ検証エラーは、レイヤー 2 の形状(エンティティ、パス(アノテーションキーとサブキーのルート)、制約の詳細)に従います。サイドとピラーの区分違反や曖昧なルーティングによる失敗は、アノテーション値が記述されたドキュメントに帰属します。そのため、Aggregate に起因する問題は [DEVELOPER_ERROR] ヘッドで、Release に起因する問題は [OPS_ERROR] ヘッドで始まり、どちらもアノテーションキー、ルーティング先のピラー、記述側、およびソースの位置を示します。
レイヤー間で共通の 1 つのエラー書式の慣例
4 つのレイヤーは、観測可能な 1 つの慣例を共有しています。Aggrega に起因するすべての検証失敗は、パスと理由を組み合わせた形をとり、問題のあるフィールドと、それを拒否した制約を示します。
- レイヤー 1(エンベロープ)とレイヤー 2(ピラースキーマ)のエラーは、同じ角括弧の先頭部分で始まります。これは問題のあるドキュメントのカテゴリと条件の短いコードで、たとえばカタログエンティティのエンベロープ不一致では
[CATALOG_ERROR E0215]、ピラースキーマが拒否する Aggregate の値では[DEVELOPER_ERROR E0168]です。その後にフィールドパスと違反したスキーマ規則が続きます。 - Layer 3(Provider ソース / Workload)のエラーは、定義上カタログエンティティに起因します。開発者の入力を拒否したスキーマを記述したのは Recipe と Provider の組だからです。これらはカタログ作成のドメインに帰属し、その帰属はメッセージ中の語としてではなく、診断の角括弧付きの先頭部分で示されます。停止するレポートは
[CATALOG_ERROR E0nnn]で始まり、カテゴリがドメインを、短いコードが条件を示します。一度発行されると固定される短いコードで照合してください。 - Layer 4(アノテーションバインディングの値検証)のエラーは Layer 2 の形に従います。検証を行う Feature スキーマは参照先の Feature の
spec.schemaにあり、実行時の値は Manifest バインディングのmapsルーティングを通じてそのスキーマに流れ、リーフごとの型チェックを受けます。
Aggrega の接頭辞付きセンチネルと、それらを生成する箇所の全一覧は errors/error-translation.md を参照してください。エラーごとのカタログ([CATALOG_ERROR] の Recipe の形に関するルールを条件ごとに記載)は errors/fatal-halts.md を参照してください。
フィールドが重複する場合のレイヤー間の相互作用
同じ記述フィールドが複数のレイヤーの対象になることがあります。Workload の containers.<name>.ports.<port> は、Workload スキーマの構造的な形状の一部としてレイヤー 1 でチェックされます。Workload のコンテンツは Component のピラーではなく Recipe 内部の構造であるため、レイヤー 2 はそれに及びません。また、プロバイダーの workloadSchema は何もチェックしません。そのため、1024 未満のポートを拒否するといった制約は Component のスキーマかアサーションに置くべきであり、そうすれば発動したレイヤーがそれを示します。
パイプライン上の配置のまとめ
| レイヤー | 適用範囲 | 実行タイミング | エラープレフィックス |
|---|---|---|---|
| 1 — JSON Schema エンベロープ | 構造的な形状(apiVersion、kind、metadata、トップレベルの spec) | 解決(ロード時) | ドキュメントのカテゴリと E0215 — カタログエンティティでは [CATALOG_ERROR E0215] |
2 — ピラースキーマ(schema: / featuresSchema / usesSchema) | ピラーごとのデータ検証(values、infra、secrets、uses) | 解決(エンベロープの後) | 作成元ドキュメントのカテゴリと条件の短いコード — Aggregate の値では [DEVELOPER_ERROR E0168] |
| 3 — Provider 機能ゲート | 合成モードのサポート(プロバイダーの機能) | 基底レンダリング | [CATALOG_ERROR] |
| 4 — アノテーションバインディングの値検証 | Manifest バインディングの maps パスを介して対象 Feature の spec.schema にルーティングされるアノテーション値の寄与 | 解決のアノテーション展開サブフェーズ(Layer 2 と並行) | スキーマ検証エラー。side と pillar の衝突 / 曖昧なルーティングのサーフェスは、作成元ドキュメント自身のドメインを先頭に付けます — Aggregate からは [DEVELOPER_ERROR]、Release からは [OPS_ERROR] |
相互参照
errors/error-translation.md— Aggrega プレフィックス付きセンチネルの一覧と、それらを生成する箇所。errors/fatal-halts.md— コンパイラが発生させるすべての致命的停止をエラーごとにまとめたカタログ。vocabulary/data-pillars.md— レイヤー 2 が検証するデータピラー(values、infra、parameters、locals、features:、uses:、provides)。entities/component.md—schema:/featuresSchema/usesSchemaに関する Component の記述箇所。entities/plugin.md—spec.provider.workloadSchemaに関する、provider レンダリングを行う Plugin の記述箇所。entities/manifest.md— Manifest のfeatures.annotationsバインディング箇所(レイヤー 4)。providers/well-known-annotations.md— レイヤー 4 が検証する、アノテーション値の解析、構造化値のサブキーへのルーティング、サブキーごとの null によるオプトアウト、およびサイド間の合成。