コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

コンパクト形式でのオーサリング

コンパクト形式は、JSON Schema 2020-12 を YAML の形で宣言的に記述する短縮記法です。作成者はフィールドごとの制約をインラインフロー形式の YAML マップとして記述し(port: { type: integer, min: 1, max: 65535, default: 8080 })、中間のオブジェクトノードは YAML の自然なネストで表し、参照には JSON Schema 標準の $ref: を使います。コンパイラは検証を実行する前にコンパクト形式を JSON Schema 2020-12 に変換するため、どちらの形式で記述されたかにかかわらず、検証、エラー報告、およびスキーマを読み取るすべてのツールは解決済みの JSON Schema に対して動作します。

このページでは、コンパクト形式の語彙、構造上の慣例、推論形式と明示形式のオブジェクトの振り分け、クロージャのセマンティクス、許可する型の配列を可能にする type: の異種性、推論形式のすべてのスコープで予約されているキーワード、および x-aggrega-* 拡張名前空間について説明します。ドキュメント間の $ref: 解決のセマンティクスについては、cross-document-ref.md を参照してください。assertions ブロックの記述文法については、templates/assertions-block.md を参照してください。データピラーの集合(values:、infra:、provides:、uses:、features:、locals:、parameters:)については、data-pillars.md を参照してください。

コンパクト形式は、schema:、parameters:、および SchemaLibrary のエントリにおける既定の記述方法です。JSON Schema YAML も同等の記述方法であり、どちらの形式も第一級の扱いで、1 つのスキーマ内で混在させることができます。2 つの形式は同じ解決済み JSON Schema ドキュメントにコンパイルされ、下流のツールや検証はどの記述方法を使ったかを意識しません。

語彙

コンパクト形式のキーワードは以下の表にあるものです。一度覚えれば、schema:、parameters:、SchemaLibrary エントリのすべてに適用できます。

型と識別のキーワード

キーワード意味コンパイル後の JSON Schema
typeフィールドの型(string、integer、number、boolean、object、array、または許可される型の配列)type:
description人間が読むためのドキュメントdescription:
defaultフィールドが存在しない場合のデフォルト値default:
required存在しなければならないフィールドに付けるリーフ単位のマーカー(required: true)フィールド名を親の required: 配列に追加します

制約キーワード

キーワード意味コンパイル後の JSON Schema
enum許可される値(リスト)enum:
const許可される唯一の値 — スカラー、マッピング、またはリストconst:
min最小値(数値)または最小長(文字列/配列)minimum:(数値)、minLength:(文字列)、minItems:(配列)— type: によって選択されます
max最大値または最大長。min に対応しますmaximum: / maxLength: / maxItems:
minLength / maxLength明示的な文字列長の制約minLength: / maxLength: に直接対応します(min/max が曖昧になる場合に使用します)
pattern文字列の正規表現パターンpattern:
format文字列が持つべき名前付きフォーマット。email、uri、hostname、ipv4、ipv6、uuid、date-time、date のいずれかです(名前付きフォーマットを参照)format:

Aggregate の parameters: ブロックでは、これらの一部は Release の値が読まれる前に、宣言そのものに対してもチェックされます。パラメータ自身の minLength と maxLength は 0 以上でなければならず、負の値は Aggregate の読み込み時に拒否されます。また、ネストされた items、properties、valuesType の契約内にあるものも含め、すべての pattern はコンパイル可能な正規表現でなければなりません。パターンはパラメータ契約の読み込み時にコンパイルされるためです。すべての format は、どの深さにあっても、以下の名前付きフォーマットのいずれかでなければなりません。ブール型またはオブジェクト型のパラメータに対する min や max も拒否されます。これらの型ではこの組は何も制限しないためです。いずれの不備も、Release がそのパラメータを指定しているかどうかにかかわらず、パラメータ名を示してビルドを停止します。ネストされた契約内の長さの上下限には、この下限は適用されません。各チェックが実行される場所については entities/aggregate.md を参照してください。

名前付きフォーマット

format は、文字列値が持つべき形を指定します。名前は JSON Schema 仕様が定義するものを、仕様と同じ綴りで使用し、それぞれ仕様が定義する意味をチェックします。

名前適合する値定義元
emailメールボックス:ローカル部(ドット区切りのアトム、または引用符付き文字列)、@、続いてドメインまたは角括弧付きのアドレスリテラル — ops@example.com。Joe <joe@example.com> のような表示名はメールボックスではありませんRFC 5321、4.1.2 節(Mailbox)
uri絶対 URI:スキーム、:、続いて残りの部分。URI の文字集合外の文字はパーセントエンコードされます — https://example.com/a%20b、s3://bucket/key。/path のような相対参照は該当しませんRFC 3986(URI)
hostnameホスト名:英字、数字、ハイフンからなるドット区切りのラベル。各ラベルは 1~63 文字でハイフンで始まらず終わらず、全体で最大 253 文字です — db-primary.data.svc.cluster.local。Punycode ラベル(xn--…)は記述どおりに受け入れられますが、ワイルドカード *、アンダースコア、末尾のドットは受け入れられませんRFC 1123、2.1 節
ipv4ドットで区切られた 0 から 255 までの 4 つの 10 進数 — 192.0.2.1RFC 2673、3.2 節(ドット区切り 4 組表記)
ipv6いずれかのテキスト形式の IPv6 アドレス(完全形、:: による省略形、または IPv4 アドレスで終わる形)— 2001:db8::1。ゾーン(%eth0)やプレフィックス長(/64)はアドレスの一部ではありませんRFC 4291、2.2 節
uuidハイフンで区切られた 8-4-4-4-12 のグループからなる 32 桁の 16 進数。大文字・小文字は問いません — 2eb8aa08-aa98-11ea-b4aa-73b441d16380RFC 4122、3 節
date-timeオフセット付きのタイムスタンプ — 2026-09-28T12:34:56Z、2026-09-28T12:34:56.5+02:00。日はその月に存在するものに限り、うるう秒は UTC の 23:59 のみですRFC 3339、5.6 節(date-time)
date暦日 — 2026-09-28 — で、日がその年月に存在するものRFC 3339、5.6 節(full-date)

フォーマットが判定するのは文字列だけです。他の型の値は、その type が判定します。また、判定するのは値の構文のみです。ホスト名が解決されることも、URI が取得されることも、メールボックスに接続することもありません。そのため、チェックはどのビルドでも同じ結果を返し、ネットワークを必要としません。

このチェックは、値がそのスキーマに対して検証されるすべての場所で実行されます。Aggregate の parameters:、Component または Feature の schema: ピラーが制約する values と infra、usesSchema: ソケットのペイロードスキーマが制約するエッジごとの values と infra、そしてそれらのスキーマが到達するすべての SchemaLibrary エントリです。provides ピラーのフォーマット名は、他のスキーマと同様にカタログの読み込み時に判定されます。Recipe が公開する値はピラーに対して検証されないため、それらに対してフォーマットはチェックされません。allOf、anyOf、oneOf、not の内部では、フォーマットに適合しない値は、他の制約に適合しない値とまったく同じく、その分岐に適合しない値となります。適合しない値は、フィールド、値、フォーマットを示して拒否されます。

表にない名前は、スキーマの読み込み時に拒否されます。値がそこに到達するかどうかは関係なく、拒否時にはサポートされる名前が一覧表示されます。そのため、emial のような綴り誤りは、何もチェックしない制約にはならず、診断になります。SchemaLibrary エントリの場合、問題の名前を確認するにはカタログ全体に対して aggrega validate を実行してください。スキーマがそのエントリに到達する Release も拒否されますが、ライブラリが見つからないと報告されます。password はフォーマットではありません。秘密情報を保持するフィールドは、代わりに sensitive: true を宣言します。

間接的に到達する形には、1 つの制限があります。フィールドの形が、他のキーワード(たとえば properties: マップ)を併記した $ref: を経由する場合、when: の then: または else: を経由する場合、あるいは宣言済みプロパティへのポインタを経由する場合、その format は、その形が直接宣言するフィールドと allOf を通じたフィールドでチェックされますが、その形の中の anyOf、oneOf、not、条件分岐の内部ではチェックされません。

合成と参照のキーワード

キーワード意味コンパイル後の JSON Schema
$refJSON Pointer フラグメントまたは外部の SchemaLibrary エントリへの参照$ref:
allOf / anyOf / oneOfJSON Schema の合成同じキーワード
patternProperties正規表現をキーとするマップ同じキーワード
valuesType型付き値マップの省略記法(例:「値がすべて文字列であるオブジェクト」)additionalProperties: { type: <X> }

コンテナキーワード

キーワード意味コンパイル後の JSON Schema
items配列要素の形items:(再帰的なコンパクト形式または JSON Schema)
properties子の明示的な宣言(ほとんど不要です。通常は YAML の構造で暗黙的に表されます)properties:
additionalProperties宣言されていないプロパティを許可するかどうか(推論形式のオブジェクトではコンパイラが付加する false。明示的な type: object では自分で記述するもので、記述しない場合は JSON Schema 自体のデフォルトである true が適用されます)additionalProperties:

Aggrega 固有のキーワード

キーワード意味
validate真偽値を返すフィールド単位の Go テンプレート述語。false の場合、validateMessage: とともに検証を停止します
validateMessagevalidate: の失敗に付随するエラーメッセージ
when条件付きのサブツリー適用。ノードの制約を適用するかどうかを決める Go テンプレート述語です
sensitiveこのリーフが秘密情報を保持することを宣言します。x-aggrega-sensitive: true にコンパイルされます。後述の「リーフを機密として宣言する」を参照してください
$jsonschemaエスケープハッチ — このノードに埋め込む完全な JSON Schema サブドキュメント
$mode曖昧な場合のための任意のディスパッチ注釈(ほとんど不要です。後述の「推論形式と明示的なオブジェクト形式」を参照してください)

借用した JSON Schema キーワード($ref、allOf、format など)は JSON Schema と同一の構文を使うため、JSON Schema を知っている作成者はすぐに認識できます。

値がデータであるキーワードは、その値を記述どおりに保持します。 default、enum、const に与えたマッピングやリストは値そのものであり、ネストされたスキーマではありません。endpoint: { type: object, default: { host: db, port: 5432 } } は endpoint のデフォルトをそのオブジェクトにし、mode: { type: object, const: { kind: fast } } はまさにそのオブジェクトだけを受け入れます。mode: { const: { kind: fast } } も同様です。const は enum と同じく、それ自体でノードをリーフにするためです。$jsonschema: エスケープハッチの内部でも同じです。

コンパクト形式のリーフの構造

記述の単位はリーフノード、つまり制約の辞書を持つフィールドです。

field_name: { type: <type>, ...constraints... }

よく使うパターン:

port: { type: integer, default: 8080 }
port: { type: integer, min: 1, max: 65535, default: 8080 }
identifier: { type: string, pattern: "^[a-zA-Z][a-zA-Z0-9_]*$" }
log_level: { type: string, enum: [debug, info, warn, error], default: info }
name: { type: string, minLength: 1, required: true }
email: { type: string, format: email }
enabled: { type: boolean, default: false }

各リーフは 1 行です。制約の辞書がフィールドの形状に関するすべてを表し、親ノードの構造がフィールドの位置を表します。

ネストしたオブジェクト

オブジェクトの構造は YAML のネストをそのまま反映します。深いネストもそのまま機能し、各リーフは引き続き 1 行で記述します:

spec:
schema:
architecture: { type: string, enum: [standalone, replication], default: standalone }
primary:
replicaCount: { type: integer, min: 1, max: 9, default: 1 }
resources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$", default: "250m" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$", default: "512Mi" }
limits:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$", default: "500m" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$", default: "1Gi" }
auth:
username: { type: string, default: app_user }
password: { type: string, sensitive: true }

コンパイラは YAML の階層からオブジェクトの構造を推論します。中間ノード(ここでは primary、resources、requests、limits、auth)は、ネストした子を含むオブジェクト型です。コンパイラは解決済みの JSON Schema に明示的な type: object ブロックと properties: ブロックを出力するため、作成者がこれらを記述する必要はありません。

推論形式と明示形式のオブジェクト

コンパクト形式のオブジェクトスコープは、2 通りの方法で記述できます。

推論形式 — 子を親キーの直下に置き、type: object 宣言は書きません。

auth:
username: { type: string, default: app_user }
password: { type: string, sensitive: true, required: true }

コンパイラは、子がプロパティ宣言であることから、そのスコープをオブジェクトとして認識します。コンパイラは type: object と properties: { ... } を出力し、コンパイル時に additionalProperties: false を自動的に挿入します。この閉包のセマンティクスは推論形式の契約の一部であり、開発者が記述したフィールドのタイプミスは明確に失敗します。

明示形式 — type: object を宣言し、properties: を列挙します。

auth:
type: object
properties:
username: { type: string, default: app_user }
password: { type: string, sensitive: true }
required: [password]
additionalProperties: true # genuinely-open map authored on purpose

明示形式では、コンパイラは additionalProperties: false を挿入しません。type: object を宣言した作成者は、閉包に関する判断の責任をすべて負います。明示形式は、真に開いたマップ(additionalProperties: true)や、その他の JSON Schema キーワード(patternProperties、propertyNames、unevaluatedProperties)を必要とするオブジェクトのための記述手段です。

記述の基準:通常の閉じたオブジェクト(カタログのスキーマで一般的なケース)には推論形式を使用します。オブジェクトを真に開いたものにすべき場合や、コンパクト形式が直接扱わない JSON Schema キーワードをスキーマが必要とする場合は、明示形式を使用します。

クロージャのセマンティクス

慣例により、コンパクト形式の推論形式のオブジェクトは閉じています。宣言されていないプロパティは検証エラーになります。コンパイラは、推論形式のすべてのオブジェクトスコープに additionalProperties: false を自動的に出力します。これは、タイプミスを明確に失敗させるというカタログの規律に沿ったものです。

オブジェクトを開く(任意の追加プロパティを許可する)には、明示形式で additionalProperties: true を使用します。

labels:
type: object
additionalProperties: true # opt-in; allow any string-keyed values

「すべての値が同じ型を持つオブジェクト」という一般的なパターン(例:ラベル用の string → string のマップ)には、valuesType: を使用します。

labels: { type: object, valuesType: string }
nodeSelector: { type: object, valuesType: string }
counters: { type: object, valuesType: integer }

valuesType: <type> は additionalProperties: { type: <type> } にコンパイルされます。単一キーワードの省略記法を設けるに値するほど頻繁に使われるパターンです。

上記の型名だけの書き方は、schema: および SchemaLibrary での表記です。Aggregate の parameters: スロットでは、代わりに値をコントラクトとして記述します — valuesType: { type: string }。値そのものがコントラクトである他の 2 つのキーワード、items: および properties: 配下の各エントリにも同じことが当てはまります。パラメーター宣言と、その中にネストされたすべてのコントラクトは、同じ 1 つの形を持つためです。パラメータースロット上のこれら 3 つの位置のいずれかに型名だけを書くと拒否され、診断メッセージにはそれを含んでいたネストされたコントラクトが示されます。パラメータースロットの語彙の全体については、entities/aggregate.md を参照してください。

必須フィールド

必須フィールドは、リーフごとに required: true を使用します:

auth:
username: { type: string, default: app_user }
password: { type: string, sensitive: true, required: true }
database: { type: string, pattern: "^[a-zA-Z][a-zA-Z0-9_]*$", required: true }

コンパイラは、オブジェクトスコープ内のすべての required: true マーカーを収集し、JSON Schema の required: [field1, field2] 配列として出力します。このマーカーは、プロパティがどこで宣言されていても有効です。推論形式のスコープ内でも、明示的な properties: ブロック内のプロパティでも同様です。

$ref: を介して SchemaLibrary のエントリーを自身のスキーマに取り込む利用側は、必須項目をどちらの方法でも指定できます。参照の横に親レベルの required: [name1, name2] 配列を書くか、そこで properties: の下に宣言したプロパティに required: true マーカーを付けるかです。完全なルールについては、cross-document-ref.md の §「クロスドキュメント $ref: における required: の構文」を参照してください。

配列

配列には type: array を使い、items: で要素の形を記述します:

tags: { type: array, items: { type: string } }
ports: { type: array, items: { type: integer, min: 1, max: 65535 } }
extraEnvVars:
type: array
items:
name: { type: string, required: true }
value: { type: string }
valueFrom: { type: object, additionalProperties: true }
allowedHosts:
type: array
min: 1 # minItems
max: 100 # maxItems
items: { type: string, format: hostname }

「型付きスカラーの配列」というよくあるケースでは、インライン形式は 1 行で済みます。オブジェクトの配列では、items: がネストされたコンパクト形式のスキーマを導入します。

type: キーワード — スカラーまたは型の配列

type: は、単一の値(type: string)か、許可される型の配列(type: [string, integer, boolean])のいずれかを受け付けます。配列形式は、「このフィールドは複数の型のいずれかを受け付ける」ことを表す JSON Schema 2020-12 の標準的な表現です。

release_tier: { type: [string, integer], description: "Numeric tier or named tag" }

type: が配列を持つ場合、値空間は指定された各型の値空間の和集合になります。配列形式を使用するスキーマを書く作成者は、下流で両方の形を扱う必要があります。解決済み JSON Schema の type フィールドは文字列か配列のいずれかを保持し、解決済みスキーマを走査するコンシューマは両方の形を確認します。

すべての推論形式スコープにおける予約キーワード

推論形式のディスパッチは、コンパクト形式の語彙レベルで意味を持つ少数のキーワードを認識します。description、type、default、required、制約キーワード(enum、const、min、max、pattern、format など)、および Aggrega 固有のキーワード(validate、validateMessage、when、sensitive)です。これらのキーワードのいずれかが推論形式のオブジェクトスコープでフィールド名として現れると、コンパイラは囲んでいるスコープをオブジェクトではなく制約リーフとして読み取ります。そのキーワードは子プロパティではなく制約として扱われ、そのスコープ内の他のすべてのキーもキーワードでなければならなくなるため、キーワードでない最初のキーは未知のキーワードとして拒否されます。

sensitive については、ここで特に触れておく価値があります。他の Aggrega 固有のキーワードと比べて、開発者が作成する実際のフィールド名としてはるかにありそうな名前だからです。sensitive という名前のプロパティを本当に必要とするスキーマ(たとえば、values が独自の sensitive フラグを公開するコンポーネント)は、type や default という名前のプロパティの場合とまったく同じように、囲んでいるスコープを明示的に宣言する必要があります。以下の明示形式か、囲んでいるスコープに $mode: jsonschema を指定するかのどちらかでこれを実現できます。$mode: jsonschema の下ではノード全体が記述された JSON Schema として読まれ、そこでは sensitive はコンパクト形式のキーワードではなく通常の内容です。

予約キーワードにちなんだ名前のプロパティを必要とするスキーマ(たとえば、開発者が作成した description: フィールド、type: フィールド、default: フィールドを持つ Component のコントラクト)では、問題のスコープに明示形式を使用します。

spec:
schema:
values:
type: object
properties:
description: { type: string } # property named "description"
type: { type: string } # property named "type"
default: { type: string } # property named "default"
required: [description, type]
additionalProperties: false

明示形式はディスパッチを回避します。properties: が子を明示的に列挙するため、キーワードの衝突は発生しません。

この制約は、すべての推論形式スコープに再帰的に適用されます。予約キーワードにちなんだ名前のプロパティを含むネストされた推論形式オブジェクトは、そのスコープで制約リーフとして読み取られます。対処法は同じで、問題のスコープを明示形式に切り替えます。

参照

参照は、JSON Schema の $ref: を構文的にも意味的にも借用しています。

resources: { $ref: "#/$defs/PodResources" }
auth: { $ref: "Datastores#/schemas/MariaDBAuth" }
secondary:
allOf:
- { $ref: "#/$defs/NodePool" }
- replicaCount: { type: integer, min: 2 }

コンパクト形式のスキーマ内の $defs: ブロックは、再利用可能な定義を宣言します。各エントリはそれ自体がコンパクト形式(または JSON Schema、あるいは混在)のスキーマです。#/$defs/<Name> という JSON Pointer フラグメントで参照します。

ブロックは、それを参照するフィールドを持つピラーの内側に、それらのフィールドと並べて宣言します。ピラーと並べてはいけません。schema: ブロックは、そのトップレベルに 3 つのデータピラー名しか受け付けないため、values: と兄弟関係に書かれた $defs: はエンティティの読み込み時に拒否され、問題のキーと、そこに置けるピラーの集合が示されます。いずれの場合も、ポインタは #/$defs/<Name> と記述します。

$defs:
PodResources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
limits:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
primary:
replicaCount: { type: integer, min: 1, max: 9, default: 1 }
resources: { $ref: "#/$defs/PodResources" }

SchemaLibrary のエントリを対象とするドキュメント間参照については、cross-document-ref.md を参照してください。OCI URI の短縮形の展開については、uri-grammar.md を参照してください。

参照はプロパティではなく定義に向ける

$defs: のエントリを指すポインタ(#/$defs/PodResources)が、選ぶべき形です。ポインタは JSON Schema が許す場所ならどこでも有効なので、宣言済みのプロパティを指すポインタも受け付けられ、適用も されますが、報告の精度が下がります。この違いは、ポインタを書く前に知っておく価値があります。

$defs: のエントリから形を得るフィールドは、フィールドごとに検査されます。失敗は、 実際に誤っている値のパスで報告され、そのフィールド配下のすべての失敗が報告されます。 最初の 1 つだけではありません。

$defs:
PodResources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
primary:
resources: { $ref: "#/$defs/PodResources" }

ここで不正な cpu は primary.resources.requests.cpu で報告されます。

宣言済みのプロパティを指すポインタから形を得るフィールドは、ドキュメント 全体の一部として検査されます。制約は引き続き適用され、制約に違反するドキュメントは引き続き停止します。ただし、失敗は その内側の値ではなくポインタを持つフィールドで報告され、そのようなフィールドが同時に複数誤っている場合でも、名前が示されるのはそのうち 1 つだけです。

primary:
resources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
secondary:
resources: { $ref: "#/properties/primary/properties/resources" }

secondary 配下の不正な cpu は secondary.resources で報告されます。

どちらの書き方も同じドキュメントを受け付け、同じドキュメントを拒否します。ただし、 Named formats で述べた format に関する制限が 1 つあります。ポインタ経由では、形の anyOf、oneOf、not の分岐内にある format は検査されません。それ以外で異なるのは、メッセージが どれだけの情報を伝えるかであり、これはマーカーがそのパスから配置されるエディタで最も重要になります。同じことは、 自身のポインタがプロパティ側へ戻って参照する $defs: エントリにも当てはまります。それを経由して 定義に到達すると、粗い報告が引き継がれます。

when: による条件付きの形

JSON Schema 2020-12 は、条件付きの形を if/then/else で表現します。コンパクト形式は、より直接的な省略記法として when: を提供します。これは Go テンプレートの述語で、真の場合はノードの残りの制約を適用し、偽の場合はノードの制約が存在しないものとして扱います。

secondary:
$ref: "#/$defs/NodePool"
when: '{{ eq $.architecture "replication" }}'
required: true
properties:
replicaCount: { type: integer, min: 2 }

述語は親のインスタンス値に対して評価されます。$ は周囲のオブジェクトスコープを指します。architecture が replication の場合、参照先の NodePool に加えて制約(required: true と、追加の replicaCount: min: 2)が適用されます。architecture が standalone の場合、これらの制約は無効になります。

述語では標準の Go テンプレート関数(Sprig)を利用できます。コンパイラは when: を JSON Schema の if/then/else にコンパイルし、検証の実行前に Go テンプレートの述語を評価するラッパーを加えます。述語はインスタンスに関して純粋であるため、決定性は保たれます。

validate: と validateMessage: によるフィールド単位のカスタム検証

制約の中には min / max / pattern / enum では表現できないものがあります。そのような場合のために、コンパクト形式は validate: を提供します。これは Go テンプレートの述語で、偽になると独自のエラーで検証を停止します。

db_size:
type: string
pattern: "^[1-9][0-9]*(Mi|Gi|Ti)$"
validate: '{{ regexFind "^[0-9]+" . | atoi | lt 100 }}'
validateMessage: "db_size must exceed 100 in its declared unit"

述語はフィールドの値(. としてアクセス可能)に対して実行され、周囲のオブジェクトのスコープは $ です。述語が偽を返すと、検証は validateMessage: を使ってエラーを生成します(指定されていない場合はデフォルトのメッセージを使います)。

validate: は JSON Schema の標準語彙を超えるケースを扱います。独自の意味的検証(semver 形式のチェック、文字列の内容が JSON であること)、あるフィールドの制約が兄弟フィールドに依存する、複数フィールドにまたがるもののスコープが狭い規則、そして完全な assertions: ブロックを書くほどではない制約です。

validate: と when: は役割が異なります。when: は制約を適用するかどうかを切り替え、validate: はそれ自体が制約です。

どの単一のフィールドも「検証対象」ではない、スコープの広い本当の意味で複数フィールドにまたがる規則には、専用の assertions: ブロックを使います。templates/assertions-block.md を参照してください。

リーフを機密として宣言する — sensitive:

values、infra、provides のリーフは、それが記述するデータが秘密情報を含むことを宣言できます。

spec:
schema:
values:
origin:
type: string
required: true
sensitive: true
description: "The credential material itself."
key:
type: string
default: value
description: "The data key the material is stored under."

sensitive: true は、解決済みの JSON Schema においてそのノード上の拡張キーワード x-aggrega-sensitive: true にコンパイルされ、他の x-aggrega-* アノテーションと並びます。コンパイラはこれを読み取り、デプロイメント内のどのアタッチメントが機密として宣言された情報を扱うかを導出し、その導出結果をコンパイル済みグラフに保持します。

宣言はデータそのものに付け、その所在を示すものには付けません。 この区別こそがこのキーワードの要点であり、逆にしてしまいやすいものです。資格情報の内容は機密ですが、それを保持するリソースの名前や、そのリソース内のデータキーは機密ではありません。どちらも公開されており、そのリソースを参照するすべてのコンシューマーに平文でレンダリングされます。所在を示すものに印を付けると、それについて事実でないことを述べることになり、その誤りが宣言を読む下流のすべてに伝播します。上の例では、origin に印が付けられ、key には意図的に付けられていません。

補完的な記述、すなわち「フィルが自身のリーフについて何を宣言しているかにかかわらず、このポイントにバインドされるものは秘密情報を扱う」という記述は、リーフの宣言ではまったくありません。それはアタッチメントスロット上の sensitive です。entities/component.md の「Attachment Slots」を参照してください。

オブジェクト全体を機密として宣言する

このキーワードはスカラーではなくオブジェクトに置くこともでき、その場合はそのオブジェクト配下のすべて、つまりオブジェクト自身の子と、さらに深くネストされたすべてを対象とします。ブロック全体が秘密情報であり、各リーフに個別に印を付けると、次に誰かが追加するリーフに印が付かないままになる場合に用いる宣言です。

オブジェクトの子は明示的な properties: ブロック内に置く必要があります。 これは推論されたオブジェクト形式が使えない唯一の箇所であり、その理由は回避するよりも理解しておく価値があります。

spec:
schema:
values:
credentials:
type: object
sensitive: true
properties: # required here
username: { type: string }
password: { type: string }

推論されたオブジェクト形式が他のあらゆる場所で許すように、子をマーカーの横に直接書くと、コンパイル時に拒否されます。最初の子が未知のキーワードとして報告され、その位置は子自身のキーになります。

values:
credentials:
type: object
sensitive: true
password: # refused: unknown keyword "password"
type: string

この拒否は回避すべき制限ではなく、正しい動作です。ノードはコンパクト形式のキーワードを持った時点で制約リーフとして読まれ、sensitive: はそのキーワードの一つです。そのため、その時点から兄弟キーはすべてキーワードでなければならず、password はキーワードではありません。properties: ブロックは「以下のキーはプロパティ名であり、さらなるキーワードではない」ことを示すものであり、Inferred vs explicit object form で説明されているのと同じ曖昧性の解消です。この診断を「マーカーはオブジェクトに付けられない」と読むのは避けるべき誤読です。付けることはでき、ブロックがそれを示す方法です。

宣言されたオブジェクト内のリーフには、独自のマーカーは必要ありません。追加しても害はありませんが、オブジェクトの宣言がすでにそれを対象としているため、新たな意味はありません。

このキーワードが行わないこと

名前からこのキーワードが実際には持たない働きが想定されがちなので、その限界を明確に述べます。

  • 何も暗号化しません。 これは宣言に対するアノテーションであり、機密保持の仕組みではありません。
  • CloudFormation テンプレートのパラメータを埋める場合を除き、検証も拒否も行いません。 リーフが機密として宣言されているという理由で値が受け入れられたり拒否されたりすることはなく、ビルド結果も変わりません。ただし、CloudFormation の Recipe または FeatureRecipe の valuesMapping が、取り込んだテンプレートのパラメータを埋めるために機密として宣言されたリーフを読む場合は、そのマッピングがバインドするすべてのリテラルがビルドを停止させるため、宣言の有無だけが異なる 2 つのビルドの結果が異なることがあります。A secret bound to a CloudFormation parameter would be written into the template(CloudFormation パラメータにバインドされた秘密情報がテンプレートに書き込まれます) を参照してください。
  • レンダリング出力に秘密情報が含まれないことを保証しません。 成果物が秘密情報を含むかどうかは、作成者がどのフィルをアタッチし、その values に何を書いたかによります。architecture/08-credential-model.md の「What the compiler does and does not guarantee」を参照してください。作成者がインラインで指定した機密宣言済みの値は、ビルドがそれをレンダリングする場所であればどこでも、宣言されていない値とまったく同じようにレンダリングされます。
  • 配信の仕組みを強制しません。 インラインの値をストア参照に変えることはできず、スロットの inject 許可リストが許可する範囲を狭めることもありません。
  • 前述の CloudFormation による拒否を除き、ビルドを停止させません。 後述するビルド時の通知は勧告です。ビルドは最後まで実行され、成果物を書き出します。通知を致命的なものにするかどうかは組織の選択であり、ビルドにアタッチされたガバナンスポリシーとして表現されるもので、キーワード自体が行うことではありません。上記の CloudFormation プロバイダーによる拒否は例外です。テンプレートに書き込まれたリテラルはスタックを読めるすべての人が読めるため、ビルドを停止させます。
  • ほとんどのターゲットではレンダリングされるバイトを変えず、それらのターゲットでは今後も変えることはありません。 独自の機密性の概念を持つターゲットプラットフォームでは、宣言が反映される先があります。そうした概念を持たないターゲットでは、宣言が変えるものは恒久的にありません。Terraform は、そのようなプリミティブを持つ唯一の標準ライブラリのターゲットです。ベンダリングされたモジュールの入力が、作成者が機密として宣言した情報を受け取る場合、レンダリング出力には、その入力に対する Terraform 自身の機密属性を記述した、生成されたオーバーライドファイルが追加されます。providers/terraform.md の「Declared-sensitive module inputs」を参照してください。それ以外のすべての場所では、既存のカタログ全体でリーフを機密として宣言しても、レンダリングされる成果物はすべて同一のままです。

ツールの出力表示で変わること

宣言が実際に変える唯一のものは、ツールが人が読むために出力する内容、すなわちデバッグ出力と、後述する拒否のテキストです。デバッグ用の出力面では、機密として宣言された値は固定テキスト <redacted> に置き換えられます。

  • aggrega build --trace が .trace/ に書き出すパスごとのトレース。
  • aggrega inspect が Aggregate について出力するノードごとの Values: ブロック。
  • aggrega inspect が解決済みの Release について出力するリーフごとのアタッチメントブロック。

キーは常に保持され、値だけが置き換えられるため、読み手はそのリーフが記述されていることと、何かが伏せられたことを引き続き確認できます。作成者が宣言していないリーフは、伏せられた兄弟の横でその値がそのまま出力されます。置き換えは宣言のみに従うため、password という名前でも宣言のないフィールドは出力され、key という名前でも宣言されたフィールドは出力されません。

宣言はその配下のすべてのリーフに及び、3 つの出力面すべてに同じように及びます。 宣言がオブジェクトに置かれている場合、そのオブジェクト内にネストされた各値も深さにかかわらず伏せられます。オブジェクトの宣言がそれらを指定しているため、伏せることで作成者が書いていないことを主張することにはなりません。照合はテキストではなくパスセグメント全体に対して行われるため、名前が宣言された名前で始まるだけの兄弟は影響を受けません。dbPassword を宣言しても dbPasswordHint は伏せられません。

伏せられた値そのものをデバッグする場合は、1 回のビルドに限りトレースでの伏せ字を無効にできます。aggrega build --trace --trace-unredacted は値をトレースファイルに書き込み、それらの各ファイルにその旨を示すヘッダーを付けます。これは呼び出し時の選択であり、設定項目はなく、トレースにのみ及びます。cli/aggrega-build.md の「Showing the withheld values」に説明があります。aggrega inspect の表示には独自の --unredacted があり、cli/aggrega-inspect.md の「Showing the withheld values」に説明があります。

この動作そのものよりも、その動作の境界のほうが重要です。

レンダリングされた成果物は決して秘匿化されません。 dist/ 配下のものはすべて、レンダリングが生成したとおりに出力されます。それがデプロイ対象そのものだからです。マニフェストにプレースホルダーを書き込めば、保護されたデプロイではなく壊れたデプロイになります。秘匿化が対象とするのはツールが表示するものであり、ツールが書き出すものでは決してありません。宣言を dist/ が公開しても安全であるという約束と読むことは、避けるべき唯一の誤読です。上で述べた限界は変わらず、dist/ は、最も多くの機密情報を運ぶアタッチメントと同じだけ機密性の高いものであり続けます。

宣言がレンダリングされた成果物に加えうるものが 1 つありますが、それは秘匿化ではありません。ターゲットが独自の機密性プリミティブを持つ場合、宣言はそこへレンダリングされます。 値は依然として完全に書き出され、何も伏せられたり置き換えられたりはしません。成果物に加わるのはその横に付くターゲット自身のマーキングであり、これによりターゲットのツールは値を作成者が宣言したとおりに扱えます。現在それを提供するターゲットは Terraform で、その属性が何を保証し何を保証しないかは providers/terraform.md の「Declared-sensitive module inputs」にあります。このようなマーキングが伝わるのは、レンダリングされた名前の同一性が宣言そのものから復元される場合に限られます。テンプレートが名前を作り出した場合、マーキングは近似されるのではなく付与されません。作成者が宣言していない値にマーキングすれば、その値について誤ったことを主張することになるからです。そのテンプレートが valuesMapping(Recipe のもの、または component にアタッチされた Feature の FeatureRecipe のもの)である場合、後述のとおりビルドがその旨を通知します。

秘匿化が及ぶのは、宣言が名指すものと、テンプレートが読み取っていると判断できるものです。 values または infra の柱にある宣言済みリーフと、sensitive と宣言された provides キーから機密情報を運ぶ配信キーは、いずれも名前で識別されて伏せられます。テンプレートが計算した値は誰も宣言していないキーの下に置かれるため、代わりにそれを識別するのは作成者が書いた参照です。トレースでは、テンプレートが sensitive と宣言されたリーフを読み取る locals: エントリや source: フィールドは伏せられ、すでに伏せられた兄弟を読み取る locals: エントリも同様に伏せられます。この読み取りは意図的に保守的です。オブジェクト全体への参照はその下にあるすべての宣言済みリーフに及び、データ全体を受け渡すテンプレートはそれらすべてに及びます。そのため、解決できない参照は表示されるのではなく伏せられます。

レンダリングされたドキュメントは再レンダリングとして表示され、その旨が示されます。 トレースのパース済み Workload は Recipe のテンプレートが生成したドキュメントです。その中には各文字がどの宣言に由来するかを記録するものがないため、内部で置換を行うべきキーが存在せず、フィールドごとにつながりを復元するには値の内容を調べる必要があります。コンパイラはそれを行いません。代わりにトレースが示すのは、sensitive と宣言されたデータがすでに置換テキストとして読まれるコンテキストに対して同じ workload: テンプレートを再評価した結果であり、ドキュメントの横の workload_note エントリでその旨が告知されます。テンプレートからは文字列があった場所に文字列が見えるため、再レンダリングは出力されたドキュメントの形を保ち、置換テキストは伏せられたデータ自身の位置に置かれます。2 つの違いが残り、ノートはその両方を記します。値の内容で分岐するテンプレートは置換テキストに対して異なるレンダリングをすること、そして軸が名指さないデータは変更されずにそのまま通ることです。これはレンダリングされたもののデバッグ用ビューであり、決してその複製ではありません。

消費されるノードの値は、そのノードの宣言に照らして、エッジがそれを運ぶ両方の表示面で伏せられます。 uses エッジのビューはターゲット component が公開したものを再現するため、ターゲット自身のスキーマがそれを支配します。ターゲットが sensitive と宣言した provides キーは、消費側が何も宣言していなくても消費側のトレースで伏せられます。エッジ自身の inject ブロックがそのキーを消費側 component の配信キーへ割り当てる場合、その配信キーも伏せられます。これはアタッチメントの inject マッピングが従うのと同じ規則で、同じ宣言を読むため、2 つの配線が食い違うことはありません。aggrega inspect のレイアウトはノード自身の柱とそのアタッチメントを表示し、消費されるノードの公開値は表示しないため、そこには伏せるべきノード間のビューはありません。

接続に記述されたアタッチメントは、それを表示するすべての表示面で、その Feature 自身の宣言に照らして伏せられます。 トレースはそれをその接続の uses エッジのビューの下、.context.uses.<alias>.features.<slot> に表示し、aggrega inspect は解決済みの Release において接続の行の下に表示します。どちらでも、その Feature が sensitive と宣言した values または infra のリーフは、同じ Feature を component に直接アタッチした場合とまったく同じように伏せられ、トレースでは、Feature が sensitive と宣言したアタッチメントの解決済み provides のキーも伏せられます。型、バージョン、ラベル、および宣言されていないすべてのリーフと provides キーはそのまま表示されるため、公開されたロケーターは、それが指し示す機密情報の横で読める状態のままです。component またはソケット上で sensitive: true を宣言するスロットは、アタッチメントが秘密の機密情報を扱うことを示しますが、それ自体でリーフを伏せることはありません。どのリーフを伏せるかは Feature が宣言するものです。

機械可読な投影は取り決めによりそのままであり、元のファイルと同じ取り扱いが必要です。 aggrega inspect --raw はエンティティを作成されたとおりに出力し、aggrega inspect --output yaml は Release を含むすべての種類について作成されたエンティティを再現します。どちらも何も置換せず、それは意図的です。これらはスクリプトがパースし diff が比較する出力であるため、自身の一部を黙って伏せる出力は、再現すると称する入力を偽り、その利用者が依存するラウンドトリップを壊してしまいます。リーフを sensitive と宣言するだけでは、それをこれらの出力から除外するには不十分です。パイプで渡す、保存する、共有する際は、Aggregate や Release そのものと同じように扱ってください。

コンパイル済みグラフは、どこで渡される場合でも伏せ処理を行う唯一の機械可読な投影です。 aggrega inspect、aggrega validate、aggrega build での --ir-graph は、実行が解決したグラフを、コマンドがすでに生成するものと並べて JSON として書き出し、デーモンの aggrega/irGraph は同じグラフをエディタに返します。いずれにおいても、作成者が sensitive と宣言した値は、読みやすいレイアウトの場合とまったく同じように置換されます。--ir-graph とともに --unredacted を指定すると代わりにそれらの値が表示され、デーモンへのリクエストの unredacted フィールドも同様です。したがって、コマンドから読んだグラフとデーモンのプロトコル経由で読んだグラフは、同じ取り扱い規則のもとでの同じドキュメントであり、作成された値を必要とするパイプラインやクライアントはそれを明示的に要求する必要があります。

宣言された値について拒否が伝える内容

作成者が sensitive と宣言した値を読むテンプレートが発する拒否は、その値を含みません。テンプレートがビルドを停止し(fail を呼び出すアサーション、評価できない式、テンプレートが生成すべきドキュメントとして読めない出力など)、その参照のいずれかが sensitive と宣言されたデータに到達する場合、報告される内容は、宣言された sensitive なデータがすべてすでに <redacted> と読まれるコンテキストに対して、同じテンプレートをもう一度評価した結果から得られます。ただし、テンプレート自身が書き出した文で停止した場合は除きます。これは以下の最初のケースです。

assertion failed: the admin password <redacted> must be supplied as a reference
  • テンプレート内に文が書き出されている fail は、書かれたとおりに報告されます。 ビルドを停止した呼び出しが、引用符で囲んだ文字列 1 つを与えた fail(fail "…" で、何もパイプで渡されず、その文に何も組み込まれていないもの)である場合、拒否は、値の内容やどの分岐がその呼び出しに至ったかにかかわらず、その文を含みます。その文はテンプレートが読んだものを何も引用しないためです。誤った形式のオリジンを拒否するアサーションは、その形式についての独自の説明を表示します。それ以外の方法で組み立てられた文(printf、フィールド、変数、fail にパイプで渡された値)は、以下のケースに従って報告されます。
  • 2 回目の評価が同じ式で同じ理由により失敗する場合、その失敗が報告されます。 作成者自身の文はそのまま残り、値があった箇所は <redacted> になります。テンプレートがエンコード、クォート、その他の変換を施した値も伏せられます。置き換えは変換より前に行われるためです。
  • そうならない場合、拒否は失敗した式を示し、そのテキストが伏せられていることを伝えます。 これは、値の内容に動作が依存するテンプレートです。置き換えテキストに対して別の分岐を取ったか、別の箇所で失敗したため、それが組み立てた内容は何も表示できません。このような拒否に理由を説明させるには、最初のケースで説明しているとおり、fail の呼び出しにその文を書き出します。拒否は引き続きビルドを停止し、そのコードも保持されます。
  • Workload スキーマが拒否したレンダリング済みの Workload は、スキーマに基づいて記述されます。 ドキュメントのフィールドは、そのテンプレートが読んだデータへのリンクを持たないため、テンプレートが sensitive と宣言されたデータを読んだ場合、値を引用し得るすべての指摘は代わりに制約を述べ、値の位置には <redacted> を置き、その理由を説明する通知を添えます。値から導かれる助言は示されません。値を引用しない指摘(キーの欠落、Workload が認めないキーなど)は通常どおりの表記になります。
.containers.main.imagePullPolicy: against /$defs/container: enum: <redacted> does not satisfy enum ["Always","Never","IfNotPresent"] (the value is withheld because the template that rendered this document reads a value declared sensitive)
  • パイプラインステップの with 入力がステップの宣言済み入力コントラクトに拒否された場合、その拒否はコントラクトに基づいて記述されます。 これは with テンプレートが sensitive と宣言されたデータを読む場合です。入力内の失敗した各位置と、それを拒否したスキーマキーワードが示され、理由を説明する通知が続き、入力が持っていた内容は一切示されません。
  • source: 座標を示す拒否は、宣言されていないものが生成した内容に基づいて記述されます。 これは、source: テンプレートが sensitive と宣言されたデータを読んでその座標を生成した場合です(ソースがロックファイルにもキャッシュにもない、キャッシュされたアーカイブがロックファイルの記録と一致しない、エンティティの横に記録されたピンがロックファイルと食い違う、など)。このような拒否が出力する各行は、ルックアップが使用した座標を示すため、ソースをその url と、要求されたバージョンまたは参照によって示します(それらを読んだ箇所において)。このようなテンプレートが生成したものはそれぞれ <redacted> で表され、理由が伏せられていることが述べられます。コードと、そのコードに対してビルドが示す対処方法は保持されます。
source-artifact https://example.com/fragments/app.yaml@<redacted>: the reason is withheld: the template producing this source reads a value declared sensitive, and the reason names what the template produced

何が宣言済みとみなされるかは、テンプレートが読めるコンテキストのあらゆる部分について、宣言が名指すものです。すなわち、コンポーネント自身の values と infra、そのコンポーネントおよび各接続にアタッチされた Features、宣言済みの素材を運ぶデリバリーキー、その Component が sensitive と宣言した provides キー、コンテキストが運ぶリストの各エントリ(後述)、そしてこれらのいずれかから計算された locals: エントリです。これらのいずれも読まないテンプレートは、どこにも宣言がない場合とバイト単位でまったく同じように報告します。 したがって、宣言された値を読んだテンプレートが発した拒否だけが異なる形で報告されます。この読み取りはトレースが使うものと同じで、テンプレートが記述する参照から読み取られます。オブジェクト全体に到達すると、その下の宣言済みのリーフすべてに到達するため、値を持たなかったテキストが伏せられることもあります。データ全体を一度に引き渡すテンプレート(後ろに何もないドットまたは $ を、toJson などの関数に渡す、出力する、名前で呼び出すテンプレートに渡す)は、その中の宣言済みの値すべてを読むため、その拒否も同じように報告されます。range または with の本体の中では、ドットはその本体が反復または名指す値であり、それを引き渡しても読まれるのはその値が持つものだけです。ここでの動作は --trace-unredacted に依存しません。このフラグが影響するのはトレースファイルだけであり、拒否はこのフラグの有無にかかわらず同じ内容になります。

宣言された値は、リストの中も含め、どこにあっても伏せられます。 1 つのリストのエントリはそれぞれ異なるエンティティによって管理され、各エントリはそれ自身のエンティティの宣言に照らして伏せられます。バウンダリ全体を対象とする FeatureRecipe が読み取る .boundary ビューでは、internal_uses_edges、outgoing_cross_boundary_uses_edges、incoming_cross_boundary_uses_edges、cross_boundary_uses_edges に列挙された各接続が、そのターゲットが公開する provides を運び、ターゲットの Component がそのキーを sensitive と宣言している場合は伏せられます。また、feature_attachments の各エントリはそのアタッチメントの infra を運び、その Feature がそのリーフを宣言している場合は伏せられます。コンポーネントにアタッチされた Feature のコンテキストでは、.context.used_by の各エントリが接続元のコンポーネントが公開するものを運び、接続元のコンポーネントの Component がそのキーを宣言している場合は伏せられます。何も宣言していないエンティティのエントリにある同じキーはそのまま引用され、伏せられたエントリから計算された locals: エントリもそれとともに伏せられます。リストを反復処理すること、または index を通じてそのエントリの 1 つに到達することは、リスト全体を読み取ることになるため、すべてのエントリが運ぶものを読み取ったものとみなされます:

error calling fail: target secret_ref "<redacted>" must start with ref-

これが及ぶのは、ビルドが発する拒否のテキストです。どの入力が宣言された値に由来するかについてプロバイダーに伝えられる情報(valuesMapping が生成した値、レンダリングされた workload: ドキュメント、各 artifacts: エントリ、omits: エントリの各フィールド)は、リストの内部から読み取られた値を数に入れません。そのため、宣言された値に対するプロバイダー自身の扱いは、上述した CloudFormation によるバインドされたリテラルの拒否も含め、そうした値には及びません。

この対象外となる拒否もあります。プラグインが書くテキスト(provider やパイプラインステップ自身の拒否)はプラグインの文であり、プラグインが書いたとおりに伝えられます。ビルドのアサーションとレンダリングの外で評価されるテンプレート(Aggregate 内のパラメータ補間とパラメータチェック、スキーマの when: と validate: テンプレート、ピンを記録する source: 座標の解決)は、失敗したとおりに失敗を報告します。

リテラルとして渡される値に対するビルドの勧告

ビルドは、宣言済みの sensitive な素材をリテラル値として運ぶデリバリーキーごとに 1 つの勧告を出力します。これは、アタッチメントの inject ブロックが、アタッチメントの Feature が sensitive と宣言した provides キーを利用側コンポーネントのデリバリーキーへルーティングし、その値が実際に渡されたときに発生します。

warning: node "db" (provider "helm"): attachment "user_password" delivers a value
declared sensitive to env delivery key "MARIADB_PASSWORD" as a literal; where the
target supports it, fill the slot with an attachment that delivers a reference instead

これについて 3 つの点は意図的なものです。

これは値がどのように渡されるかを報告するものであり、何かが誤っていることを報告するものではありません。 リテラルを渡すことが、ターゲットが受け付ける唯一の方法であることはよくあり、まさにそれを行うために存在するアタッチメントの系統もあります。勧告は、どの値がその経路を通り、どこで通るかを作成者に伝え、その選択を暗黙のままにせず可視化します。その選択が誤りであるとは主張しません。

これは警告であり、停止になることはありません。 ビルドは成功し、成果物を変更せずに書き出します。リテラルで渡される認証情報でビルドを失敗させたい組織は、それをビルドに対するガバナンスポリシーとして表現します。拒否はそこに属するものであり、一部のデプロイメントが破らざるを得ない規則はコンパイラのデフォルトではありません。

これは配線から判断され、値から判断されることはありません。 勧告は、スキーマが宣言した sensitivity と作成者が書いたデリバリーを読みます。値は検査されないため、フィールドがその名前や内容から認証情報であると推測されることはなく、たまたまパスワードを保持している宣言されていない値は何も発生させません。

2 つのケースは意図的に何も報告しません。参照先の provides キーが何も公開しないデリバリーキーは、リテラルを渡さず、何も報告しません。勧告は実際に行われたデリバリーを追うためです。また、inject 許可リストが空のスロットはデリバリーを Recipe に委ねるため、作成者は報告対象となるデリバリーキーを書いておらず、対処すべきこともありません。

この勧告は独自のクラスであり、独自のコードをキーとし、--no-unsupported-field-warnings では抑制されません。このフラグが対象とするのはターゲットの忠実度に関する通知であり、それは別の理由で抑制される別の判断です。また、言語サーバーが --build-on-inspect(または serve.build_on_inspect 設定キー)を有効にして動作している場合は常に、この勧告はエディタにも届き、Aggregate 上の問題として表示されます。この設定は aggrega inspect との一貫性のためにデフォルトで無効です。ターミナルコマンドはグラフを検査する間にレンダリング段階へ到達しないため、このような勧告も発生させません。同じく何も発生させないエディタの検査は、ターミナルと同じものを示していることになります。設定を有効にすることで、エディタに追加の層を要求できます。その際ディスクには何も書き込まれません。段階は実行され、その成果物は破棄されます。追加されるのはビルドがレンダリング中に発生させる勧告であり、ビルドが停止するチェックは一切追加されません。公開される各問題はそれを発生させた層を示すため、エディタはこの勧告を、解決段階と解析段階が報告するものと区別できます。

マッピングがマークなしでレンダリングする値に対するビルドアドバイザリ

ビルドは、作成者がまだ制御手段を持っているにもかかわらず、レンダリングがマークを伝えられない宣言済みセンシティブな values リーフごとに 1 件のアドバイザリを出力します。これは、値が valuesMapping の出力である source: からのレンダリングで発生します。対象となるのは、Component が宣言するリーフに対する Recipe のマッピング、またはコンポーネントにアタッチされた Feature の FeatureRecipe のマッピングで、その Feature が宣言するリーフに対するものです。マッピングの出力キーはマッピング独自のものであるため、どの宣言もそれらを指しておらず、ターゲットはそのリーフについてキーごとのマークを受け取りません:

warning: node "api" (provider "terraform"): attachment "token": "values.token" is declared
sensitive, but FeatureRecipe "terraform/api-token" maps its values through a valuesMapping
whose output keys no declaration names, so the target receives no per-key sensitivity
marking for it; ...

この行は、作成されたときの座標でリーフを示し、結合を制御するマッピングを持つ Recipe または FeatureRecipe を示します。宣言とマッピングが 2 つの異なるエンティティに書かれているためです。アタッチメントの行はアタッチ時の名前から始まるため、1 つのコンポーネント上にある 1 つの Feature の 2 つのアタッチメントを区別できます。マッピングを取り除くことが制御手段です。マッピングがなければ、ソースのレンダリングが受け取る値は宣言されたリーフのパスをキーとし、マークもそれとともに伝わります。アーティファクトのみのレンダリングとワークロードのみのレンダリングは、ターゲットに値のマップをまったく渡さないため何も出力しません。境界にアタッチされた Feature も同様で、空の values ピラーに対してレンダリングされます。そこでは上記の上限が恒久的であり、警告を出してもすべきことを示せません。リテラルとして伝わる値に対するアドバイザリと同様に、これは警告であって停止ではなく、レンダリングされたバイトを一切変更せず、独自のコード sensitivity-not-conveyed を持つ独自のクラスであり、--no-unsupported-field-warnings では抑制されません。完全な形式は Warnings and Linter Output に記載されています。

宣言が読み取られる場所と読み取られない場所

キーワードは、それが置かれたノード上で読み取られ、その後、宣言がそのデータに到達しうるすべての経路をたどります。ネストされたプロパティマップ、各合成ブランチ、そして $ref のターゲットです。ブランチと参照ターゲットはどちらも、それを持つプロパティ上に合成されるため、いずれかを通じて見つかった宣言はそのプロパティについて収集されます。パスを延長するのは properties への降下だけです。

マーカーは、これらのキーワードの横にあっても、キーワードが到達する先の内部にあっても読み取られるため、次の 2 つの形では意図的な配置は不要です:

  • $ref の横、または参照先の内部。 参照元リーフ上のマーカーはそのリーフを宣言します。参照先スキーマ内のマーカーも参照元リーフについて収集され、そのリーフのパスにその下のチェーンを加えた位置になります。作成された値が存在しない定義内部のパスになることはありません。
  • 合成キーワード (allOf / anyOf / oneOf) の横、またはブランチ自身の properties の内部。 ブランチはそれを持つオブジェクト上に合成されるため、すべてのブランチが降下対象となり (JSON Schema として作成されたノードの条件付きブランチも含みます)、その内部の宣言は合成元プロパティ自身のパスにそのチェーンを加えた位置で収集されます。

次の 1 つの形では、マーカーを意図的に配置する必要があります:

  • 配列リーフ自体に配置します。items の要素型には配置しません。要素がセンシティブな素材を持つ配列は、配列の位置でセンシティブと宣言します。要素型はプロパティマップではなく、降下の対象にならないためです。

parameters: は別のボキャブラリです

sensitive は parameters: の型付きコントラクトのボキャブラリには含まれません。パラメータエントリでこれを宣言した Aggregate は、Aggregate の読み込み時に拒否され、問題のキー自体の位置で unexpected property: "sensitive" を報告するドキュメントエンベロープの診断が出ます。パラメータのコントラクトは閉じたオブジェクトであるため、これはそのボキャブラリ外のどのキーも受ける扱いと同じです。

この非対称性は意図的なものです。センシティビティの軸はカタログエンティティが宣言する 3 つのデータピラーを対象としており、パラメータはピラーのリーフではなく環境コントラクトの入力です。パラメータを通じて認証情報を引き上げる方法は architecture/08-credential-model.md の「Legacy charts that demand a formatted string」に記載されており、そこではその方法がもたらすトレードオフが説明されています。

allOf、anyOf、oneOf による合成

合成キーワードは JSON Schema と同様に機能します。

# Inherit and extend
secondary:
allOf:
- { $ref: "#/$defs/NodePool" }
- replicaCount: { type: integer, min: 2 }
# Disjunction (one of several shapes)
auth:
oneOf:
- existingSecret: { type: string, required: true }
- rootPassword: { type: string, required: true }
username: { type: string, default: app_user }
password: { type: string, required: true }

コンパイラは、解決済みの JSON Schema に同じ合成キーワードを出力します。合成される各エントリは、それぞれコンパクト形式、JSON Schema、または $ref: 参照のいずれでも構いません。1 つの合成の中でこれらを混在させることもサポートされています。

エスケープハッチ — $jsonschema:

compact form の語彙を超えるケース($dynamicRef、unevaluatedProperties、深い not: の合成、再帰型)では、任意のノードで完全な JSON Schema に切り替えられます。

values:
architecture: { type: string, enum: [standalone, replication] }
some_complex_field:
$jsonschema: |
type: object
unevaluatedProperties: false
allOf:
- $ref: "#/$defs/Foo"
- not:
required: [conflicting_field]
patternProperties:
"^x-": { type: string }
$defs:
Foo:
type: object
properties:
name: { type: string }

$jsonschema: ブロックには JSON Schema の YAML を記述します。コンパイラはこれを透過的なパススルーとして扱い、その内容はそのノードの位置で、解決済みの JSON Schema ドキュメントにそのまま入ります。検証、エラー報告、ツールはすべて解決済みのドキュメントに対して動作します。このエスケープは純粋にオーサリング上の利便性のためのものです。

not: 分岐には、それが除外する形状がなぜ拒否されるのかを述べる description: を付けられます。その分岐に一致する値は、汎用の「not allowed here(ここでは許可されていません)」という文言の代わりに、その説明を理由として 1 行で出力して拒否されます。そのため、拒否された値の作成者が読むべき文として記述します。使用されるのは not: 分岐自体に書かれた説明だけです。分岐が参照しているだけの $defs エントリーに書かれた説明は使用されません。

ブロック内のすべてのノードは JSON Schema として読み取られ、そこに書かれたコンパクト形式のキーワードはコンパクト形式での意味を保ちます(文字列に対する min: 3 は引き続き最小長です)。ブロック内の $ref はブロック外と同じように解決されます。#/$defs/Foo はピラーの $defs: のエントリを指すため、例ではそこで Foo を宣言しています。誰も宣言していないエントリを指す参照は、エンティティの読み込み時に拒否されます。$dynamicRef は $dynamicAnchor に対して解決されるため、再帰的な形を記述できます。再帰の深い位置で検証に失敗した値は、それを保持するフィールドで報告されます。children の項目が { $dynamicRef: "#node" } であるツリーで 2 階層下にある不正な name は、tree.children で報告されます。

unevaluatedProperties と unevaluatedItems には 1 つの制限があります。 参照、合成キーワード(allOf、anyOf、oneOf)、条件、または依存スキーマも持つノードに記述した場合、どちらも読み込まれますが強制されません。また、unevaluatedItems は contains の横でも強制されません。上の例では unevaluatedProperties: false が allOf の横にあるため、Foo も patternProperties も extra を宣言していないにもかかわらず、{ name: n, extra: 1 } は受け入れられます。

$jsonschema: によるエスケープはドキュメント単位ではなく、ノード単位です。1 つのスキーマで、単純な部分には compact form を、1 つの複雑なフィールドには JSON Schema のエスケープを、共有される形には $ref: を使うことができ、これらすべてを 1 つのドキュメント内で行えます。

1 つのドキュメント内でのコンパクト形式と JSON Schema の混在

コンパクト形式と JSON Schema は、任意のノード境界で自由に混在させることができます。振り分けの規則は内容の形に基づきます。

  • $jsonschema: を含むノードは JSON Schema(エスケープハッチ)として扱われます。
  • JSON Schema 形式のトップレベルキーワード(type:、properties:、additionalProperties:、if: など)を含むノードは JSON Schema(明示形式)として扱われます。
  • プロパティ名 → 子スキーマのエントリのみを含む(JSON Schema の予約キーワードを含まない)ノードは、コンパクト形式(推論形式)として扱われます。
  • $ref: のみを持つノードは参照のパススルーです。
  • allOf: / anyOf: / oneOf: を持つノードは合成であり、各エントリはそれぞれ独立して振り分けられます。

コンパクト形式のリーフでは、標準的なパターンは field_name: { type: ..., constraints... }、つまり既知のコンパクト形式の語彙を含む YAML マップです。振り分けでは、制約の辞書をそのキーによって認識します。

まれに曖昧になるケース(たとえば、推論形式の振り分けが JSON Schema のキーワードとして解釈してしまう、文字どおり type という名前のフィールドを持つコンパクト形式のスキーマ)では、明示形式が正規の解決策です。前述の「推論形式のすべてのスコープにおける予約キーワード」を参照してください。

ファイルからのコントラクトのインポート — $import:

コントラクトは、それを宣言するエンティティの内部に置く必要はありません。$import: は、コントラクトを読み込むファイルを指定します。

spec:
schema:
$import: ./contracts/api-server.schema.yaml

この場合、spec.schema 全体がそのファイルから読み込まれます。そのファイルは置き換え対象のブロックとまったく同じように記述します。最上位にピラーを置き、その下にコンパクト形式または JSON Schema の YAML を記述します。

contracts/api-server.schema.yaml
values:
greeting: { type: string, enum: [hello, howdy], default: hello }
infra:
image_tag: { type: string, default: "1.0" }
provides:
host: { type: string }

単一のピラーだけをインポートし、その兄弟要素をその横にインラインで記述することもできます。

spec:
schema:
values:
$import: ./contracts/values.yaml
infra:
image_tag: { type: string, default: "1.0" }

同じ形式は、usesSchema: ソケットの valueSchema: と infraSchema: でも使用できます。

適用される規則は次のとおりです。

  • $import: は、それが現れる位置で唯一のキーでなければなりません。 その横に兄弟キーを記述すると、どちらか一方が破棄されるのではなく、拒否されます。
  • 相対パスは、それを宣言したエンティティファイルを含むディレクトリを基準に解決されます。ビルドを実行するディレクトリが基準になることはありません。これは valuesMapping:、workload:、artifacts: が使用するのと同じ基準です。パスはそのディレクトリ内にとどまる必要があります。エンティティの公開物に含まれるすべてのファイルはそこから取得されるためです。そのディレクトリの外へ出るパスや絶対パスは、エンティティとともに配布されないファイルを指すことになり、拒否されます。A path names content outside the entity’s own directory(パスがエンティティ自身のディレクトリ外のコンテンツを指しています)を参照してください。複数のエンティティで共有するスキーマは SchemaLibrary に置き、$ref: で参照します。
  • インポートされたファイルはエンティティとともに配布されます。 公開されたエンティティは、そのスキーマがインポートする各ファイルを、チェーン内のすべてのファイルを含めて保持します。そのため、レジストリから取得したコピーも同じコントラクトを読み込み、それに対して記述された値を検証します。aggrega push を参照してください。
  • インポートされるファイルはスキーマの内容を保持するものであり、エンティティドキュメントではありません。 内容が YAML マップでないファイルは、そのファイル名を示して拒否されます。
  • インポートされるファイル自体が単一の $import: であってもかまいません。この場合は再帰的に解決されます。すでに読み込み中のファイルに戻るチェーンは、そのチェーンを示して拒否されます。

インポートはエンティティの読み込み時に行われるため、そのエンティティを読み込むすべての箇所、つまり aggrega validate、ビルド、aggrega push、aggrega inspect、エディタが同じコントラクトを参照します。読み込めないファイルやスキーマではない内容は、コントラクトを未適用のまま残すのではなく、その時点で拒否されます。また、push は何かが公開される前にそれを拒否します。

$import: と $ref: は互換ではありません。$import: はファイルを指定して内容全体を置き換えます。$ref: は SchemaLibrary のエントリを ID で指定し、任意のノードで合成します。ライブラリ ID やレジストリホストを含む $import: の値は拒否され、$ref: の使用が案内されます。cross-document-ref.md を参照してください。

Aggrega 拡張名前空間 — x-aggrega-*

コンパクト形式は、x-aggrega- で始まるあらゆるキーワードを Aggrega 固有の拡張として認識します。この名前空間は開かれており、新しいアノテーションはキーワードごとの語彙の編集なしにカタログに加わります。x-aggrega-selector、x-aggrega-narrowed-from、あるいは将来のアノテーションを記述した作成者は、コンパイル時に拒否されることなく、その内容を解決後の JSON Schema の適切なスコープに配置できます。

名前空間のプレフィックスは重要です。x-agrega-source(g が 1 つ欠けている)のようなタイプミスは拡張キーワードとして認識されず、推論形式のスコープにおける閉じたオブジェクトのセマンティクスによって拒否されます。プレフィックスのスコープは、カタログのアノテーション面に対するタイプミス検出の網として機能します。

特定の x-aggrega-* アノテーションは、パイプライン内の既知の箇所でコンパイラが出力します。

  • x-aggrega-selector: — usesSchema: および featuresSchema: の合成処理が、互換性のある provider Components を対象とするセレクタ文字列を保持するために出力します。
  • x-aggrega-sensitive: — sensitive: true を宣言したリーフが出力します。前述のリーフを機密として宣言するを参照してください。

独自の拡張キーワードを記述するカタログ作成者も同じ名前空間を使用します。コンパイル済みの JSON Schema を利用する下流のツールは、JSON Schema 自体のキーワード空間と衝突することなく x-aggrega-* キーを読み取ります。

実例 — MariaDB Component スキーマ

MariaDB データストア向けの代表的なコンパクト形式の Component スキーマです。全体を通じた推論形式、混在したリーフ制約、参照、条件付きの形状、そして認証ブロックに対する oneOf の実例を示します。

spec:
schema:
values:
architecture:
type: string
enum: [standalone, replication]
default: standalone
description: |
Topology mode. `standalone` runs a single primary; `replication` runs a primary
plus N secondary replicas governed by the secondary block.
primary:
replicaCount: { type: integer, min: 1, max: 9, default: 1 }
resources: { $ref: "#/$defs/PodResources" }
persistence: { $ref: "#/$defs/PersistenceSpec" }
secondary:
when: '{{ eq $.architecture "replication" }}'
properties:
replicaCount: { type: integer, min: 2, max: 8, default: 2 }
resources: { $ref: "#/$defs/PodResources" }
persistence: { $ref: "#/$defs/PersistenceSpec" }
auth:
oneOf:
- existingSecret: { type: string, required: true }
- rootPassword: { type: string, sensitive: true, required: true }
username: { type: string, default: app_user }
password: { type: string, sensitive: true, required: true }
database: { type: string, pattern: "^[a-zA-Z][a-zA-Z0-9_]*$", required: true }
metrics:
enabled: { type: boolean, default: false }
serviceMonitor:
enabled: { type: boolean, default: false }
namespace: { type: string }
labels: { type: object, valuesType: string }
$defs:
PodResources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
limits:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
PersistenceSpec:
size: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi|Ti)$", required: true }
storageClass: { type: string }

JSON Schema YAML で記述すると、同じコントラクトではすべてのオブジェクトの type: object、properties:、additionalProperties: false を書き出し、必須フィールドを親の required: に改めて列挙する必要があるため、かなり長くなります。この簡潔さによる利点は、より大きな Component コントラクトほど積み重なり、コンパクト形式を schema:、parameters:、および SchemaLibrary エントリのデフォルトの記述手段とするのに十分な意味があります。

相互参照

  • ドキュメント間の $ref: 解決のセマンティクス(ドキュメント間参照の横に置く required: 構文、ライブラリからライブラリへのチェーン展開、利用側によるライブラリの絞り込み)については、cross-document-ref.md を参照してください。
  • assertions: ブロックの記述文法(コンパクト形式の validate: では表現できないフィールド横断のルール)については、templates/assertions-block.md を参照してください。
  • コンパクト形式のスキーマを収容するデータピラーのセット(values:、infra:、provides:、uses:、features:、locals:、parameters:)については、data-pillars.md を参照してください。
  • OCI URI の短縮表記の展開ルール(ドメインのデフォルト、レジストリセグメント、バージョンのフォールバック、パブリッシャーの展開)については、uri-grammar.md を参照してください。
  • SchemaLibrary エンティティの記述($ref: で参照可能なスキーマがカタログ内のどこに置かれるか)については、../entities/schemalibrary.md を参照してください。