ドキュメント間の `$ref:` 解決
このページでは、Aggrega のスキーマ記述面におけるドキュメント間 $ref: 参照の解決セマンティクスを説明します。具体的には、$ref: がドキュメントの境界を越えてライブラリを参照する際に Components、Features、SchemaLibrary エントリの作成者から見える動作と、どの記述形式がドキュメント間展開と問題なく連携するかを定める構文ごとの required: ルールです。
$ref: は JSON Schema 2020-12 にネイティブなものです。schema: の内容(Component、Feature、SchemaLibrary エントリ)の中、コンパクト形式のスキーマの中、そして usesSchema: と featuresSchema: が出力する合成された JSON Schema レイヤーの中に現れます。このページでは、$ref: が別ファイルまたは OCI アーティファクト内の SchemaLibrary エントリを対象とする、ドキュメント間のケースを扱います。
カタログエンティティの継承(Component が Component を拡張する場合)については、inheritance-and-interface.md を参照してください。Release が Release を拡張するのは、カタログでインデックスされないドキュメントに対する別の仕組みであり、entities/release.md で説明しています。
$import: はドキュメント外の内容を参照するもう一つのキーワードであり、両者は異なる問いに答えます。$ref: は SchemaLibrary 内のエントリ をアイデンティティで指定します。カタログがそれを解決し、ロックファイルがバージョンを提供します。また、任意のノードで合成できます。$import: はエンティティと同じ場所にある ファイル を指定し、内容全体をそのファイルの内容で置き換えます。$import: はスキーマ面だけでなく、valuesMapping:、workload:、artifacts:、parameters: でも使用できます。スキーマに対する $import: については、compact-form-authoring.md の §「Importing a contract from a file」を参照してください。
$ref: の解決セマンティクス
$ref: は JSON Schema 2020-12 の標準的な解決に従います。実際には次の参照形式が使われます。
- 同一ドキュメント内のローカルフラグメント:
{ $ref: "#/$defs/PodResources" }— スキーマの$defs配下にあるPodResourcesエントリに解決されます。 - アイデンティティによる SchemaLibrary エントリ参照:
{ $ref: "WebPrimitives#/schemas/URL" }— 名前のみの<Library>#/schemas/<Entry>形式です。ライブラリ名は解決済みのカタログに対して解決され、#/schemas/<Entry>という JSON Pointer フラグメントがエントリを選択します。バージョンは参照ではなくロックファイルによって指定されます。参照はレジストリホストを持ちません。ホストを含むoci://<host>/…形式はコンパイル時に拒否され、アイデンティティ形式を使うよう作成者を誘導する診断が出力されます。そのため、物理的なレジストリの場所が作成されたソースに入り込むことはありません。ライブラリのバイト列がどこから提供されるか(ローカルのカタログディレクトリ、コンテンツキャッシュ、またはリモートレジストリ)はリゾルバーの関心事であり、解決時に束縛され、参照の一部になることはありません。 - ファイルパスは参照先になりません:
{ $ref: "./schemas/foo.yaml#/definitions/Foo" }はスキーマのコンパイル時に拒否され、<Library>#/schemas/<Entry>形式を示す診断が出力されます。エンティティの隣のファイルに置かれたスキーマ内容は、代わりに$import:で取り込みます。これは、エンティティが読み込むすべてのファイルと同様に、エンティティ自身のディレクトリの範囲内に制限されます。
参照はコンパイル時に解決されます。エキスパンダーは参照された内容をコンシューマーのスキーマにインライン展開し、レンダリングされた IR には間接参照ではなくインライン展開された内容が含まれます。
$ref: は JSON Schema の合成キーワードと自然に組み合わせられます。
secondary: allOf: - { $ref: "#/$defs/NodePool" } - replicaCount: { type: integer, min: 2 } - description: "Replication-mode secondary instances."allOf は、参照された NodePool の形状と追加の制約を合成します。
ドキュメント間 $ref: における required: の構文
カタログ作成者は、Component または Feature に必須プロパティを宣言する際、2 つの記述形式のいずれかを選びます。リーフレベルのマーカー(各プロパティに required: true)か、親レベルの配列(オブジェクトのスコープに required: [name1, name2, ...])です。どちらの形式も JSON Schema 2020-12 では有効であり、このセクションで示す位置に記述すれば、ドキュメント間の $ref: 展開のもとでもどちらも有効です。
$ref: を使わない推論形式の記述 — リーフレベルのマーカーはコンパイル時に集約されます。コンパイラは各プロパティを走査し、リーフが required: true を持つ場合、そのプロパティ名を合成された親の required: 配列に追加します。
spec: schema: values: database: { type: string, required: true } display_name: { type: string, required: true } default_locale: { type: string, default: "en-US" }コンパイラは親スコープに required: [database, display_name] を出力します。
$ref: を持つ利用側 — ドキュメント間の $ref: の横に書けるのは properties、required、description だけであり、利用側が追加する必須項目はそこに書いたものです。つまり、親レベルの required: 配列か、properties: の下に宣言したプロパティに付けたリーフレベルの required: true マーカーです。参照先エントリ自身の必須項目(推論形式でのリーフレベルのマーカー、またはそれ自身の required: 配列)は、参照を通じてそのまま適用されます。親レベルの配列では、エントリがすでに宣言しているプロパティを再宣言せずに必須項目を指定できます。
spec: schema: values: $ref: "Datastores#/schemas/PostgresPayload" required: [database, display_name]リーフレベルのマーカーも、利用側が参照の横で宣言したプロパティに付ければ有効です。そこで properties: { database: { type: string, required: true } } と書くと、required: [database] とまったく同様に database が必須になります。利用側のプロパティはエントリの同名のプロパティを置き換えるため(利用側によるライブラリエントリの絞り込みを参照)、意図する形で再宣言してください。
ライブラリ間のチェーン展開
SchemaLibrary のエントリは、それ自体が別の SchemaLibrary のエントリを指す $ref: を含むことができ、これによりチェーンが生じます。コンパイラはコンパイル時にチェーンをたどります。エントリの展開中に出会った各 $ref: もまた、それを保持するライブラリの文脈で展開されます。
# Library Aspec: schemas: DatabasePayload: type: object properties: host: { type: string } credentials: { $ref: "Credentials#/schemas/BasicAuth" }
# Library B (referenced from library A above)spec: schemas: BasicAuth: type: object properties: username: { type: string } password: { type: string }DatabasePayload を参照するコンシューマーの Component は、credentials にライブラリ B の BasicAuth が展開された、完全に展開済みのシェイプを受け取ります。チェーンが追加した制約に違反する値は、検査対象のドキュメント内のその値自身のパスで拒否され、その拒否は制約の由来となったライブラリエントリを示しません。それを見つけるには、コンシューマーから $ref: チェーンをたどってください。
コンシューマーによるライブラリエントリの絞り込み
コンシューマーの Component は、ライブラリエントリから取り込まれたプロパティと同じ名前のプロパティを宣言できます。この場合、マージされたシェイプでは、コンシューマーのコンパイル済みプロパティがライブラリエントリのプロパティを完全に置き換えます。
# Library entryspec: schemas: ToolContract: type: object properties: side_effects: type: array items: { type: string, enum: [read, write, delete] }
# Consumer Componentspec: schema: values: $ref: "Tools#/schemas/ToolContract" properties: side_effects: type: array items: { type: string, enum: [read] } default: [read]マージされたシェイプでは、side_effects はコンシューマーのより狭い契約(enum: [read]、default 付き)を反映し、ライブラリエントリのより広い enum: [read, write, delete] はなくなります。このプロパティはコンシューマーが記述したものです。
これは想定どおりの動作です。コンシューマーがライブラリエントリのプロパティを絞り込むことは、標準的な絞り込みパターンです。絞り込みは暗黙的に行われ、コンシューマーのプロパティはそれ自体の来歴に基づきます。
相互参照
- カタログエンティティの継承(Component-extends-Component、Feature-extends-Feature)については、inheritance-and-interface.md を参照してください。
- 参照がカタログエンティティではなくファイルを指すデプロイ側ドキュメント間の継承について:Release を拡張する Release は
entities/release.mdに、Manifest を拡張する Manifest はentities/manifest.mdに記載されています。 - プロバイダ固有のソースポインタ(
Recipe.spec.source.chart:、Recipe.spec.source.modulePath:)については、エンティティごとの Recipe のドキュメントを参照してください。Provider のソースポインタは$ref:の下に統一されておらず、プロバイダプラグインがそれらを直接利用します。 - OCI URI の短縮形の展開規則(ドメインのデフォルト、文脈に応じたエンティティの展開、解決の優先順位、バージョンの扱い)については、uri-grammar.md を参照してください。