URI 文法とフォーマット文字列の一覧
Aggrega のエンティティは、複数の異なる記述位置に現れる URI 文字列を通じて互いを参照します。同じ URI の形(core/postgres:1.0.0)が 5 つ以上のエンティティ種別の文脈に現れ、コンパイラはシジルやプレフィックスではなくスキーマ上の位置からエンティティ種別を推論します。YAML ファイルを読む、または保守する作成者は、core/postgres:1.0.0 が Component 型、Aggregate モジュール、Recipe、FeatureRecipe、Wasm プラグインのどれを指すのかを知るために、位置に基づく解釈規則を念頭に置いておく必要があります。
このページでは、すべての位置にわたる URI 文法、Manifest のマッピング階層におけるバージョン付きとバージョンなしの type: キーの優先順位規則、OCI URI の短縮形の推論規則、そしてドキュメント全体にわたるより広範なフォーマット文字列の一覧(Go テンプレート構文、Sprig 関数、JSON Schema 2020-12 の宣言、JSONPath、glob パターン、SemVer 正規表現)をまとめます。「Aggrega はこの文字列をどう扱うのか」を知りたい作成者は、ここで答えを見つけられます。
位置に基づくエンティティ種別の推論
同じ URI 文字列でも、スキーマ内のどこに現れるかによってエンティティ種別の意味が異なります。次の表は、Aggrega がエンティティ参照 URI を期待するすべての位置と、推論されるエンティティ種別を列挙したものです。
| Position | 推論されるエンティティ種別 | OCI パスの展開 |
|---|---|---|
Aggregate.spec.components.<id>.type | Component | /component/{publisher}/{category}/{name} |
Aggregate.spec.subsystems.<name>.components.<id>.type | Component(components と同じ — サブシステムはコンポーネントのグループ化です) | /component/{publisher}/{category}/{name} |
Aggregate.spec.aggregates.<id>.type | Aggregate(サブアグリゲートモジュール) | /aggregate/{publisher}/{name} |
Aggregate.spec.components.<id>.features.<id>.type | Feature | /feature/{publisher}/{name} |
Aggregate.spec.components.<id>.features.<id>.type | Feature(認証情報 — feature.aggrega.ai/kind: secret のラベル付き) | /feature/{publisher}/{name} |
Manifest.spec.mappings.components.type.<key> | Component(ルックアップキーとして使われる URI)。値は Recipe URI です | キー: /component/、値: /recipe/{provider}/{name} |
Manifest.spec.mappings.components.name.<id> | Recipe(粒度の細かいオーバーライドバインディング) | /recipe/{provider}/{name} |
Manifest.spec.mappings.features.type.<key> | Feature(ルックアップキー)。値は FeatureRecipe URI です | キー: /feature/、値: /featurerecipe/{provider}/{name} |
Manifest.spec.mappings.features.name.<id> | FeatureRecipe(粒度の細かいオーバーライドバインディング) | /featurerecipe/{provider}/{name} |
Manifest.spec.mappings.features.annotations.<key>.feature | Feature(アノテーションによるバインド) | /feature/{publisher}/{name} |
Recipe.spec.implements | Component(インターフェース契約) | /component/{publisher}/{category}/{name} |
FeatureRecipe.spec.implements | Feature(インターフェース契約) | /feature/{publisher}/{name} |
Component.spec.extends / Feature.spec.extends | Component / Feature(継承チェーンの親) | /component/{publisher}/{category}/{name} または /feature/{publisher}/{name} |
Manifest.spec.extends | Manifest(マッピング継承チェーンの親) | URI の位置ではありません — 相対パス、または Release の隣にある Manifest の素の metadata.name |
Release.spec.extends | Release(継承チェーンの親) | URI の位置ではありません — Release ファイルへの相対パスのみで、それ以外の形式はありません |
Release.spec.aggregate | Aggregate(Release のデプロイ対象) | /aggregate/{publisher}/{name} |
Release.spec.manifest | Manifest(Release のマッピングロックファイル) | URI の位置ではありません — 相対パス、または Release の隣にある Manifest の素の metadata.name |
FeatureRecipe.spec.pipeline.<step>.plugin | Wasm プラグイン | /plugin/{pluginType}/{name} |
3 つの位置が掲載されているのは、作成者が URI を期待してこれらを使おうとしますが、実際には URI ではないためです。 Manifest と Release はカタログでインデックスされるエンティティではなく、互いに隣り合って作成されるデプロイ側のドキュメントであるため、どちらの extends: も、また Release の manifest: も、カタログやレジストリに対して解決されません。Release の manifest: はファイル、または Release の隣にある Manifest の素の metadata.name を指します。2 つの extends: の位置では、値はファイルを指し、いずれの位置にレジストリ座標を書いても拒否され、受け付けられる形式が診断メッセージに示されます。また、2 つの extends: の位置は書き方も同じではありません — Manifest は Release の隣にある Manifest の素の metadata.name も受け付けますが、Release は相対パスのみを受け付けます。Release の形式については entities/release.md を、それぞれの拒否で示される内容については errors/fatal-halts.md を参照してください。
推論規則は、YAML スキーマ上の位置がエンティティ種別を決定するというものです。特定の type: フィールドがどのエンティティ種別を参照しているかを作成者に示す表面上のマーカー(シジル、プレフィックス、スキーマレベルのアノテーション)はありません。作成者は YAML を読む際に位置に基づく規則を念頭に置きます。ツール(エディターの補完、aggrega inspect)は同じ規則を読み取り、エンティティ種別に応じた候補を提示します。
2 つの URI 形状 — 導出座標を持つプラグインとメタデータで種別を持つカタログエンティティ
カタログエンティティの URI は種別を示す記号を持ちません(前節を参照)。Plugin URI は意図的にその対極にあります。プラグインの URI は、分類のためのセグメント、つまりソケットタイプをパスに直接記述します。この 2 つの参照ファミリーは意図的に異なる読み方をするようになっており、URI がどちらのファミリーに属するかがわかれば、その分類をどこで確認すべきかがわかります。
Plugin の座標はプラグインのタイプから導出されます。 プラグインの参照は oci://hub.aggrega.ai/plugin/<pluginType>/<name> です。この座標は導出されたものです。<pluginType> セグメントと素の <name> は、プラグインのアドレッシングブロック、すなわち metadata.pluginType と metadata.name から取られ、パスに組み立てられます。ソケットは名前にパスとしてエンコードされず、metadata.name は素の名前です。導出された座標がそのままレジストリ(および組み込みプラグインセット)のキーとなるため、レジストリはプラグインをソケットごとに整理します。コアプラグインは plugin/provider/helm、plugin/linter/publishing、plugin/parser/yaml のような座標に解決されます。いずれも素の metadata.name(helm、publishing、yaml)とその metadata.pluginType(provider、linter、parser)を組み合わせたものです。<pluginType> セグメントはプラグインのソケットタイプそのものです。同じ素の <name> でも pluginType が異なれば別のプラグインになります。導出される座標、ひいてはアイデンティティが異なるためです。<pluginType> セグメントの分類の基準となるソケットの分類体系の全体については、entities/plugin.md を参照してください。
カタログエンティティは種別をメタデータに持ちます。 記述される参照は <publisher>/<category>/<name> です(例: core/datastore/postgres)。エンティティの kind: はファイル内にあり、URI のエンティティ種別は、前述の位置に基づくエンティティ種別の推論に従ってスキーマ上の位置から推論されます。パスは種別ではなくカテゴリで整理されます。Component はカテゴリセグメントを持ち(core/datastore/postgres)、Recipe または FeatureRecipe はレンダリング機能を最初のセグメントとして持ち(helm/postgres)、残りの種別はフラットな <publisher>/<name> です。パスのどこにもエンティティ種別は記述されません。
2 つの形が異なる理由。 Plugins はレジストリ内でソケットごとに整理されるため、ソケットのセグメントが自然なレジストリキーとなり、すべてのプラグイン URI に含まれます。カタログエンティティはレジストリ内でカテゴリごとに整理されるため、パスが記述するのは種別ではなくカテゴリです。したがって URI は、プラグインについてはパスだけでソケットを示しますが、カタログエンティティの種別はファイルを読んで初めてわかります(種別は metadata にあり、参照箇所では位置がそれを与えます)。この非対称性は意図的なものです。各ファミリーのパスは、そのファミリーがレジストリ内でどのように整理されているかを反映しており、両者に一律の文法を課すものではありません。
URI 形状 — バージョン指定ありとバージョン指定なし
上記のすべての URI 位置は、3 つの形式のいずれかで参照を受け付けます。バージョン指定なし、またはコロンの後に厳密なバージョンかキャレット範囲で固定する形式です。
| 形式 | 例 | セマンティクス |
|---|---|---|
| バージョン指定なし | core/postgres | 位置の解決セマンティクスに応じて、「任意のバージョン」または「最新の登録済みバージョン」に解決されます |
| 厳密な固定 | core/postgres:1.0.0 | 特定の 1 つのバージョンに固定します。バージョンはセマンティックバージョンで、すべてのエンティティの metadata.version が取る形式です |
| キャレットによる固定 | core/postgres:^1.0.0 | 指定されたバージョンと互換性のある最も高いバージョンを選択します。^1.0.0 の場合、1.0.0 以上かつ 2.0.0 未満です |
固定指定は参照の最後のコロンの後のテキストであり、そのテキストが / を含まない場合に限ります。したがって、ポート付きのレジストリホストへの参照(localhost:5000/core/postgres)は固定指定を持ちません。ポートのコロンの後のテキストは参照の続きです。
これらのいずれの形式でもない固定指定、つまりテキストがバージョン範囲として読めないキャレット(core/postgres:^garbage)や、セマンティックバージョンではない厳密な固定指定(core/postgres:1.x、core/postgres:1.0、core/postgres:v1.0.0)は、どのバージョンも指定しません。コマンドがそのような参照を解決しようとして解決できない場合、拒否のメッセージは、カタログが保持していないエンティティやバージョンを報告するのではなく、参照、固定指定、および上記の 3 つの形式を示します。この診断は errors/fatal-halts.md の「A version pin is none of the forms a pin takes(バージョンの固定指定が固定指定の取るいずれの形式でもありません)」で説明されています。固定指定はその時点でのみ判定されるため、不正な固定指定によってどの参照が解決されるかが変わることはなく、利用可能などのバージョンも満たさない正しい形式の固定指定はそのとおりに報告されます。固定指定の文法を記述するスキーマはないため、不正な固定指定はファイルの読み込み時ではなく、何かが参照を解決する時点(aggrega validate、aggrega pull、aggrega build)で報告されます。
これらの形式は同じ位置に共存します。作成者は、バージョンの固定が必要か、バージョンの柔軟性が必要かに応じて選択します。Manifest の mappings.{components,features}.type 階層は、両方のバリアントを別々の辞書キーとしてサポートし、バージョン指定ありがバージョン指定なしに優先する優先順位を持ちます。両方が同じ検索に一致する場合、バージョン指定ありのキー(core/api-server:1.0.0)がバージョン指定なしのキー(core/api-server)より優先されます。2 つのバリアントは排他的ではなく、両方を同じ type: マップに置くことができ、リゾルバは最も具体的なものを選びます。Provider のディスパッチは解決済みの Recipe の spec.capability フィールドから決まるため、Manifest は型を Recipe にマッピングするだけです。
エンティティごとのバージョン利用の仕組み(どのエンティティのバージョンフィールドが実際に解決ディスパッチで利用され、どれが記述的な来歴にとどまるか)については、vocabulary/inheritance-and-interface.md の「Cross-entity version consumption」を参照してください。
Component、Feature、Aggregate、Plugin への参照はキャレット範囲(core/postgres:^1.0.0)も受け付け、どの形式であっても、すべてのコマンドが適用する 1 つの規則により、カタログが保持するバージョンのうち条件を満たす最も高いバージョンを選択します。version-resolution.md を参照してください。選択ではなくマッピングの整合性チェックである 3 形式の implements: 照合については、10-status.md の「Version matching」を参照してください。
場所ではなくアイデンティティ
正規のエンティティ参照は、プラグイン参照も含めて、場所ではなくアイデンティティです。エンティティが何であるかを示し、現在どこにあるかは決して示しません。
アイデンティティはベアでホストを含みません。レジストリホストを持たず、ホストは default_registry を通じて設定から与えられ、解決時に束縛される解決座標です。レジストリの移転や、同じエンティティの別の場所へのミラーリングは設定の変更であり、そのエンティティを指す参照は変更されません。
アイデンティティはバージョンも含みません。参照は、どのバージョンがそれを満たすかを制約するために任意のバージョンピン(:<version> または :^<version>)を持つことができ、各 Release は解決された正確なバージョンをロックファイルにピンとして記録しますが、バージョンはアイデンティティに組み込まれるのではなく、アイデンティティとは別に与えられます。
解決時に、コンパイラはベアのアイデンティティを設定されたホストおよびピン留めされたバージョンと結合し、具体的なバイト列に到達します。両者は別々に与えられるため、同じ参照は、それを指すソースを編集することなく、別のレジストリや別のピン留めされたバージョンに対して解決されます。
OCI URI 短縮形の推論
作成者はすべての URI を完全修飾の OCI URI として記述する必要はありません。コンパイラは解決時に 4 つの直交する推論ルールを適用し、短縮形の記述を正規の OCI URI に展開します。ルールは次のとおりです。
ルール 1 — ドメインのデフォルト
ドメインを持たない URI には、.aggrega-config.yaml で設定された default_registry(デフォルト: hub.aggrega.ai/)が前置されます。
# Shorthandtype: core/postgres:1.0.0
# Equivalent canonical formtype: hub.aggrega.ai/component/core/postgres:1.0.0ルール 2 — コンテキストに基づくエンティティの展開
コンパイラはスキーマ上の位置に基づいて、適切なエンティティ種別のセグメントを付加します。対応関係は上記の位置推論表と同じです(/component/、/aggregate/、/recipe/、/featurerecipe/、/feature/、/plugin/)。
# Same string, two positions, two expansionsAggregate.spec.components.foo.type: core/postgres:1.0.0# → hub.aggrega.ai/component/core/postgres:1.0.0
Manifest.spec.mappings.components.type."core/postgres:1.0.0": helm/postgres:1.0.0# Key: hub.aggrega.ai/component/core/postgres:1.0.0# Value: hub.aggrega.ai/recipe/helm/postgres:1.0.0ルール 3 — 3 層の優先順位
OCI 推論を適用する前に、コンパイラは architecture/13-catalog-and-registry.md に記載された 3 層エンティティ解決モデルによって URI を解決します。
- ローカルパス — Release とその Manifest が指定するドキュメント向け。 Release の
aggregate、manifest、extends、または Manifest のextendsを./または../プレフィックス付きで記述すると、Release 自身のディレクトリからの相対ファイルとして読み込まれ、OCI 推論は実行されません。それ以外の位置はパスを受け付けません。./…と記述されたtype、Manifest のマッピングのキーまたは値、implements、パイプラインのpluginはどのエンティティも指さず、ビルドを停止させます。ローカルで作成したエンティティは、ワークスペースルートのcatalog/の下、またはworkspace.catalog_dirsに列挙されたディレクトリに置かれ、ワークスペースとキャッシュの階層を通じて名前で解決されます。 - ワークスペースとキャッシュ — ワークスペースのカタログ検索スタック、次にキャッシュ。
.aggrega-config.yamlのワークスペースのcatalog_dirs:ディレクトリ(または、設定がworkspace.releasesの下で独自のディレクトリを指定している Release の場合は、その Release のディレクトリ)が記述順に検索され、ワークスペースルートのcatalog/ディレクトリは最後に、つまり列挙されたすべてのエントリの後に、そのディレクトリが存在する場合にのみ検索されます。スタック内のどこかで一致すると、OCI 推論は省略されます。一致しない場合は、次にartifact_cache_dirが参照されます。ここには、以前のレジストリからのプルで取得されたものが保持されています。 - レジストリ。 ワークスペースとキャッシュの階層で見つからない場合、OCI 推論の規則が適用され、参照は
aggrega pull、または--auto-pullかワークスペースのauto_pull設定を指定して実行したビルドによって、リモートレジストリから取得されます。どちらもないビルドは、ロックファイルが固定するものだけを読み込みます。
このカスケードにより、プロジェクトは Release がパスで指定するドキュメント(ローカルパス階層)と、ベンダリングされたカタログコンテンツやワークスペースローカルのカタログコンテンツ(ワークスペースとキャッシュの階層)、およびリモートから取得したレジストリコンテンツ(レジストリ階層)を組み合わせて使用できます。エンティティ参照は、後の 2 つのうちどちらがエンティティを保持していても同じ方法で記述します。
catalog_dirs: に複数のディレクトリが列挙されている場合、そのリストは順序付きの先勝ちの優先順位スタックです。複数の列挙ディレクトリに存在するエンティティ識別子は、最も先に列挙されたディレクトリに解決され、後の出現は隠されます(エラーではなく上書きです)。そのため、プロジェクトは自身のカタログディレクトリを共有ディレクトリの前に重ね、識別子単位でエンティティを上書きし、残りはそのまま下の層に委ねることができます。上書きは解決の詳細に報告されます。単一のディレクトリ内で 2 つのファイルが同じ識別子を主張する場合は、引き続き記述上の誤りであり、読み込みは停止します。
ワークスペースルートの catalog/ ディレクトリはそのスタックの先頭ではなく末尾に置かれるため、プロジェクトが列挙したものは衝突時にこれより優先され、無関係なディレクトリを 1 つ列挙してもこれが読み込まれなくなることはありません。列挙されたエントリがすでにこのディレクトリに到達している場合はスキップされます。列挙されたディレクトリの走査は再帰的なため、ワークスペースルートを指定したスタックはすでにこれを読み込んでいます。catalog_dirs: を省略することと空のリストとして記述することは異なる意味を持ちます。省略した場合、ワークスペースは引き続き catalog/ を読み込みます。[] と記述した場合はローカルカタログをまったく読み込まず、これがワークスペースにカタログがないことを示す方法です。
ルール 4 — バージョンの扱い
URI はバージョンセグメントを含めることも省略することもできます。バージョンの扱いは解決位置(Manifest の層解決、implements: のマッチング、サブ Aggregate のインポート)に依存し、その位置自身のバージョン消費ルールに従います。エンティティごとのバージョンのセマンティクスについては、inheritance-and-interface.md の「Cross-entity version consumption」を参照してください。
フォーマット文字列一覧
URI 文字列以外にも、Aggrega の記述面には複数の異なるフォーマット文字列の慣例があります。YAML ファイルを記述または読む際には、さまざまな位置で次のフォーマットに出会います。
| フォーマット | 記述場所 | 検証主体 |
|---|---|---|
Go テンプレート({{ .field }}) | Recipe の valuesMapping: / workload: / artifacts: / provides: / locals: / source:、FeatureRecipe の injectMapping: / パイプラインの with:、Aggregate の parameters: の補間、Release の directory: / subDirectory: | 評価時の Go テンプレートパーサー。記述箇所ごとの利用可否ルールは templates/expansion-matrix.md を参照 |
Sprig 関数参照({{ default 1 .v }} など) | Go テンプレートと同じ記述面 | テンプレートエンジン初期化時に登録される Sprig v3 FuncMap。ヘルパーの全一覧は templates/sprig-functions.md を参照 |
| JSON Schema 2020-12(コンパクト形式または完全形式) | Component / Feature の schema: の内容(または SchemaLibrary のエントリへの $ref:) | 解決中のエンティティ読み込み時の JSON Schema バリデーター |
| JSON Pointer(RFC 6901) | Recipe の locals.<*_path>: キー(volumes_path、containers_path など)、FeatureRecipe の pipeline: ステップ出力の参照、Wasm プラグインの JSONPatch ペイロード | Wasm プラグイン契約に基づく RFC 6901 のベースライン。plugins/plugin-contract.md で宣言 |
| SemVer 正規表現 | すべてのエンティティの metadata.version フィールド | エンティティスキーマごとの JSON Schema 正規表現 ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-...)?$ |
バージョン固定(:<version>、:^<version>) | 上記のすべての URI 位置における、エンティティ参照のバージョンセグメント | 参照を解決する際のコンパイラ。完全一致の固定はセマンティックバージョンであること、キャレット固定は範囲が解析できることを確認し、不正な固定はそれ自身の条件で拒否されます。上記の URI の形 を参照 |
| ファイルシステムパス | カタログ相対パス(例: .aggrega-config.yaml の catalog_dirs: エントリ)、workload: / artifacts: / valuesMapping: 内の Recipe の $import: ファイルパス | 解決時に記述どおりに読み込まれます。catalog_dirs: のエントリはそれを宣言する設定ファイルからの相対パス、$import: のパスはエンティティ自身のディレクトリからの相対パスです。グロブは展開されないため、* はその名前のファイルまたはディレクトリを指します |
| ラベルセレクター式 | Component.spec.usesSchema.<socket>.selector、Feature の appliesTo: / appliesToAnyOf: | セレクターが評価される場所での Aggrega セレクターパーサー。セレクターの文法は vocabulary/modifier-system.md に記載 |
アノテーションキーの形(<namespace>/<name>) | metadata.annotations のキー、Manifest の features.annotations のキー、境界アノテーションのカスケード | エンティティごとの JSON Schema 正規表現。予約プレフィックスの規律は vocabulary/labels-and-annotations.md を参照 |
Provider 名。任意でバージョンを固定(helm、helm:^1.0.0) | Recipe.spec.capability; FeatureRecipe.spec.capability | Provider ディスパッチの検索。どのプラグインのバージョンも満たさないピンはビルドを停止させます |
注入配信キー(env.<KEY>、file.<path>、arg.<flag>) | Aggregate の inject: ブロック、FeatureRecipe の injectMapping: 出力 | vocabulary/topology-triad.md の注入スキーマ |
各フォーマットには独自の文法、独自のバリデーター、独自のエラー報告の形があります。フォーマット文字列の解析エラーに遭遇した場合は、フォーマットごとのリファレンスで構文ルールを確認してください。
作成中にエディターがこれらのエラーを報告します。aggrega serve は送られた各ドキュメントをその種別のスキーマに対して検証し、ビルドと同じ判定を返します(cli/aggrega-serve.md の「ライブ検証」を参照)。また、aggrega scaffold は任意の種別の初期ドキュメントを下書きします。
相互参照
entities/manifest.md— Manifest のマッピング階層の解決と、コンテキスト認識型の短縮 URI のセクション。entities/plugin.md— Plugin のソケット分類と、ソケットをエンコードしたplugin/<socket>/<name>形式の URI。architecture/13-catalog-and-registry.md— 3 階層のエンティティ解決モデルと、カタログ配布のための正規の OCI 分類。vocabulary/inheritance-and-interface.md—implements:によるインターフェースバインディングと、エンティティ間のバージョン利用。templates/expansion-matrix.md— Go テンプレート形式文字列の、テンプレート記述箇所ごとの利用可否ルール。templates/sprig-functions.md— テンプレートエンジンに組み込まれた Sprig v3 ヘルパーの一覧。vocabulary/topology-triad.md— inject 配信キーの慣例。セレクター式の文法はvocabulary/modifier-system.mdにあります。vocabulary/labels-and-annotations.md— アノテーションキーの形式と、予約済みプレフィックスの運用規律。10-status.md—implements:の 3 形式マッチング、および参照を解決する CLI コマンドの準備状況。