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

SchemaLibrary

SchemaLibrary は、再利用可能な JSON Schema 2020-12 の定義と、任意のパラメータ化されたヘルパーを保持するカタログエンティティです。スキーマの形状(URL、期間、共通のプローブ構造、繰り返し現れるリソース制限など)を共有する Components と Features は、それらの形状をライブラリで一度だけ宣言し、正規の $ref URI を介して参照します。このライブラリエンティティは Tier 3 であり、Component をまたいだスキーマの再利用を必要とするカタログのためのオプトイン機能です。繰り返されるスキーマ内容を持たないカタログは、SchemaLibrary なしで提供されます。

SchemaLibrary の役割

プラットフォームアーキテクトは、カタログ全体で繰り返し現れるスキーマの形状を一元化するために SchemaLibraries を作成します。ライブラリはデプロイ可能な構成要素ではなく、定義の名前空間です。Component / Feature の作成者は、ライブラリのエントリを正規の $ref URI で参照します。型は一度だけ定義され、参照が解決されるすべての場所で検証されます。

「ライブラリ」と「利用側」の分離は意図的なものです。Components はインスタンスが満たす契約(その values、infra、provides、ソケット、認証情報スロット)を宣言します。Features は振る舞いの付加を表現します。SchemaLibraries はスキーマの内容、すなわち値が満たすべき構造上のルールのみを表現します。この 3 つの役割を分けておくことで、各エンティティの種類はそれぞれのペースで進化できます。共有のスキーマ定義を必要としない作成者が、ライブラリエンティティに触れることはありません。

エンティティエンベロープ

SchemaLibrary エンティティは、標準的なカタログエンベロープを持ちます。apiVersion: aggrega.ai/v1beta1 と kind: SchemaLibrary がエンティティの種類を示し、metadata.name は PascalCase の識別子で、metadata.version は厳密なセマンティックバージョニングに従います。ライブラリの内容は spec の下に置かれます。spec.schemas は必須で(ライブラリは少なくとも 1 つのエントリを宣言する必要があります)、spec.templates は任意です(ライブラリがパラメータ化されたヘルパーを使用する場合にのみ存在します)。

apiVersion: aggrega.ai/v1beta1
kind: SchemaLibrary
metadata:
name: WebPrimitives
version: 1.0.0
spec:
schemas:
URL:
type: string
pattern: "^https?://"
HTTPMethod:
type: string
enum: [GET, POST, PUT, PATCH, DELETE]

スキーマエントリーの記述

スキーマエントリーは 3 つの形式のいずれかで記述します。コンパクト形式は、短く一般的な形状(type、pattern、enum、min、max などの 1 行で書ける制約)のための既定の記述方法です。JSON Schema 2020-12 の YAML は、JSON Schema の機能をすべて必要とするエントリー(合成キーワード、条件付きの形状、複雑な $defs)のための、対等な記述方法です。1 つのエントリー内で両者を混在させることは、コンパクト形式コンパイラがノードごとに内容の形状に応じて処理を振り分けることでサポートされています。コンパクト形式で意図を表現できない場合は、$jsonschema: エスケープハッチによって、任意のノードに完全な JSON Schema の内容を埋め込めます。

エントリー内の format は、どのスキーマにおいても同じものを検査します。email、uri、hostname、ipv4、ipv6、uuid、date-time、date のいずれかを指定し、利用側がそのフィールドに与える値は、その形式でない限り拒否されます。vocabulary/compact-form-authoring.md を参照してください。それ以外の形式(password を含む)を指定するエントリーはライブラリの読み込み時に拒否されます。そのため、カタログ全体に対する aggrega validate は、まだどこからも参照されていなくてもそのエントリーを拒否し、ライブラリ、エントリー、形式名を示して、サポートされている形式を列挙します。また、Release がそのライブラリに到達するビルドやプルは、そこで停止します。別のライブラリを参照するエントリーは、Component または Feature のピラーがそれを利用する箇所で判定されます。秘密情報を持つフィールドは、形式ではなく sensitive: true を宣言します。

テンプレートと $instantiate:

繰り返しの構造を多く持つライブラリは、spec.templates の下にパラメータ化されたヘルパーを宣言します。テンプレートは $params: マップ(名前と型を持つパラメータ宣言)と本体(パラメータを $<paramName> スカラートークンとして参照する compact form または JSON Schema のコンテンツ)を持ちます。スキーマエントリは $instantiate: と $args: のバインディングによってテンプレートをインスタンス化します。置換エンジンはパラメータのプレースホルダーをリテラルのスカラー値で置き換え、解決されたエントリの本体を生成します。

spec:
schemas:
LivenessProbe:
$instantiate: ProbeTemplate
$args:
port: 8080
path: /healthz
ReadinessProbe:
$instantiate: ProbeTemplate
$args:
port: 8081
path: /ready
templates:
ProbeTemplate:
$params:
port:
type: integer
path:
type: string
type: object
properties:
port:
type: integer
const: $port
path:
type: string
const: $path

置換はリテラルのスカラー値に限られます。置換エンジンは Go のテンプレート構文を解釈せず、条件式の評価やループの実行も行いません。より表現力のあるヘルパーが必要な作成者は、ライブラリのエントリを独自のバリエーションとともに利用する Components または Features を構成します。

命名の慣例

ライブラリ名、スキーマエントリのキー、テンプレート名は PascalCase に従います。エンティティエンベロープの JSON Schema は、パターン制約によって 3 か所でこの慣例を強制します。

  • metadata.name は ^[A-Z][A-Za-z0-9]*$ に一致します。
  • spec.schemas のマップキーは、propertyNames によって同じパターンに一致します。
  • spec.templates のマップキーは、propertyNames によって同じパターンに一致します。

spec.schemas または spec.templates に PascalCase でないキーを持つ SchemaLibrary は、ワークスペースのロード時にエンベロープ検証で失敗します。エンベロープレベルでの強制は重要な役割を担っています。スキーマエントリのキーは正規の $id URI (#/schemas/<name>) に現れ、テンプレート名はインスタンス化の時点で正規の URI を参照します。PascalCase でないキーをロード時に検出することで、それらがカタログのエコシステム全体に広がることを防ぎます。

テンプレートの $params: マップ内のパラメータ名はテンプレートローカルです。正規の $id URI には現れず、エンベロープレベルでのパターン制約も受けません。作成者はテンプレートのパラメータに合った任意の命名の慣例に従います。port、path、intervalSec のような小文字のパラメータ名が一般的です。

ライブラリ、スキーマ、テンプレートの各レベルで命名が統一されているため、参照識別子が読みやすくなります。WebPrimitives#/schemas/URL は一目で理解できます。

ドキュメント間の $ref: 解決のセマンティクス($ref: が SchemaLibrary の境界を越えてどのように解決されるか、$ref: を持つ利用側における required: 構文の違い、ライブラリ間のチェーン展開、利用側がライブラリを絞り込む動作)については、vocabulary/cross-document-ref.md を参照してください。

ライブラリエントリの参照

Component / Feature の作成者は、ライブラリエントリをそのアイデンティティ、つまりベア名形式 <Library>#/schemas/<name> で参照します。

# Inside a Component schema:
spec:
schema:
values:
healthCheck:
$ref: "WebPrimitives#/schemas/URL"

ライブラリ名は解決済みカタログに対して解決され、#/schemas/<name> フラグメントがエントリを選択します。参照はレジストリホストを含みません。作成者は任意で最小バージョンの下限を <Library>:<version>#/schemas/<name> として指定できます(バージョン区切り文字は : で、recipe/feature のマッピングおよびロックファイルのピンと一致します)。ただし、解決されるバージョンは Release ごとのロックファイルによって提供され、ロックファイルは利用される各ライブラリを名前 + バージョン + コンテンツダイジェストでピン留めします。レジストリホストを含む参照(oci://<host>/… 形式)はコンパイル時に拒否され、作成者をアイデンティティ形式へ誘導する診断が出力されます。そのため、物理的なレジストリの場所が作成されたソースに入り込むことはありません。ライブラリのバイト列がどこから提供されるか(ローカルのカタログディレクトリ、コンテンツキャッシュ、またはリモートレジストリ)はリゾルバの関心事であり、解決時に束縛されます。レジストリの移転はリゾルバ設定の変更であり、ソースの変更ではありません。

禁止されている JSON Schema キーワード

JSON Schema 2020-12 のキーワード $dynamicAnchor と $dynamicRef は、SchemaLibrary のエントリでは禁止されています。SchemaLibrary パーサーはワークスペースの読み込み時にスキーマエントリとテンプレート本体の両方をスキャンします。公開リンターは公開時に冗長なガードを適用します。インスタンス化エンジンはパラメータ置換後に解決済みの本体を再スキャンするため、パラメータ値を介して禁止キーワードを紛れ込ませるテンプレートも失敗します。これら 3 つのスキャンを組み合わせることで、静的な導入経路(スキーマエントリまたはテンプレート本体内のリテラルの $dynamicAnchor)、パラメトリックな導入経路($dynamicRef を含む $args: の値)、および帯域外ツールによる回避経路(パーサーを経由しなかったものは公開時のガードが捕捉します)が塞がれます。

拒否が発生すると、エラーには問題のキーワードとファイルパスが示されます。作成者は最初のインスタンス化時ではなく作成時にエラーを確認できます。テンプレート本体も読み込み時のスキャンの対象から除外されません。

動的参照のセマンティクスはランタイム評価と結び付いており、コンパイラのコンパイル時決定性の契約を損ないます。動的参照の動作が必要な作成者は、静的な $ref 解決を使うようにスキーマを再構成します。このチェックにオプトアウトはありません。

Tier の配置

SchemaLibrary は、エンティティ Tier のドキュメントモデルにおける Tier 3 であり、Component をまたいでスキーマを再利用する必要があるカタログ向けのオプトイン機能です。繰り返し現れるスキーマ内容を持たないカタログは、SchemaLibrary エンティティを一切含めずに出荷されます。Tier の表示は、ドキュメントのナビゲーション上「上級者向け。不要であればスキップ」を示すものであり、機能の有無を示すものではありません。コンパイラは SchemaLibrary を他のカタログエンティティ種別と同様に扱います。ワークスペース読み込み時には同じエンベロープ検証を、エントリごとの内容には同じ JSON Schema 2020-12 パイプラインを、リリース時には同じ OCI 公開パイプラインを適用します。

Tier 3 の中でも、spec.templates によるパラメトリックヘルパーの仕組みはそれ自体がオプトインです。相当量の繰り返し構造を持つライブラリ(ポート + パスでパラメータ化した Probe テンプレート、許可オリジンでパラメータ化した CORS テンプレート、証明書 + 鍵のパスでパラメータ化した TLS テンプレートなど)は、templates による再利用の恩恵を受けます。多様な単発のエントリを持つライブラリは、テンプレートブロックを完全に省略し、各エントリを spec.schemas の下にインラインで記述します。