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

Aggrega Catalog (Component) スキーマ

自動生成されたリファレンスです。手動で編集しないでください。公開されている JSON Schema から再生成してください。

スキーマ ID: https://aggrega.ai/schemas/component-v1beta1.schema.json

アトミックな構成要素の抽象的な定義です。

Component エンティティの作成に関する解説は Component 作成リファレンスを参照してください。このページでは、そのリファレンスが説明する構造スキーマを記述します。

トップレベルの型: object

プロパティ

プロパティ種類必須説明
apiVersionconst “aggrega.ai/v1beta1”はい定数: "aggrega.ai/v1beta1"
kindconst “Component”はい定数: "Component"
metadataobjectはい
specobjectはい開発者の不透明な values ペイロードを管理する検証定義とスキーマ定義。

追加のプロパティは許可されません。

component.metadata

プロパティ種類必須説明
namestringはい1 文字以上。
versionstringはいインターフェースの厳密なセマンティックバージョニング(例: 1.0.0)。パターン: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$。
descriptionstringいいえこのエンティティが何であり、何のためのものかを、使用するかどうかを判断する人に向けて書きます。まずそれが何かを示す一文で始め、次に読者がそれを選び正しく使うために必要なこと、つまりそれをデプロイする Release に何を期待するか、そしてその振る舞いについて意外な点を加えます。通常は短い段落程度の長さです。
maintainersobject[]いいえこのエンティティを所有するメンテナーの一覧です。
licensestringいいえこのエンティティが記述するソフトウェアのライセンスの SPDX 識別子です(MIT や AGPL-3.0 など)。記録するのはそのソフトウェアの条件であり、このファイルの条件ではありません。
repositorystringいいえソースファイルが置かれている Git リポジトリの URL です。
homestringいいえこのエンティティのホームページ、wiki、またはドキュメントの URL です。
keywordsstring[]いいえUI での発見性を高めるための説明的なキーワードの一覧です。
labelsobjectはい特性を宣言するためのダックタイピングのラベル。予約済みの ‘component.aggrega.ai/type’ キーを含める必要があります。
annotationsstring のマップいいえDomain 2 で Platform Architect が記述する、不変かつ固有のコンポーネント特性。.context.annotations.catalog バケットへカスケードされます。

追加のプロパティは許可されません。

component.metadata.maintainers[]
プロパティ種類必須説明
namestringはい
emailstringいいえ
urlstringいいえ

追加のプロパティは許可されません。

component.metadata.labels

特性を宣言するためのダックタイピングのラベル。予約済みの ‘component.aggrega.ai/type’ キーを含める必要があります。

プロパティ種類必須説明
component.aggrega.ai/typestring (enum)はいこのコンポーネントがどのような種類のものかを示す予約済みの軸。このキーと受け付ける値は Aggrega が定義するため、集合は閉じています。独自の軸でコンポーネントを分類するには、このキーと並べて独自のラベルキーを追加します。許可される値: "server"、"worker"、"task"、"function"、"stateful-server"、"resource"

component.spec

開発者の不透明な values ペイロードを管理する検証定義とスキーマ定義。

プロパティ種類必須説明
extendsstringいいえこの Component が拡張するベース Component の URI。拡張は構造を合成します。ベースのメタデータのラベルとアノテーション、アタッチメントスロット(featuresSchema)、自己注入の許可リスト(inject)、トポロジーソケット(usesSchema)が継承され、この Component はそれらに追加することも、継承したエントリをキーごとに置き換えることもできます。ベースのデータピラーは合成されません。ベースの schema ブロックはベースが記述したとおりに継承されるため、拡張する Component は schema: inherited と記述し、独自のピラー内容は記述しません。
featuresSchemaobject のマップいいえ宣言的なアタッチメントスロットの定義。このエンティティが Feature のアタッチを期待する、名前付きのバインディングポイントです。スロットは、どのフィルがバインドできるか(selector)と、フィルのマテリアルをどのように配信できるか(inject)を制約します。フィル自身の Feature が、その values と infra の契約を所有します。スロットを宣言してもアタッチメントブロックが閉じることはありません。作成者はどのスロットも宣言していない名前で Feature をアタッチできるため、1 つのエンティティがスロットを埋めるアタッチメントと、より広いスコープで共有される認証情報の両方を担えます。スロットはバインディングポイントであり、依存ソケットではありません。別個のトポロジーの面は usesSchema が宣言します。
injectstring[]いいえ許可リストに登録された自己注入の配信メカニズム(例: [‘env’, ‘file’, ‘arg’])。存在する場合、開発者は Aggregate 内のコンポーネントレベルで inject: ブロックを使い、自身の values や provides のキーを配信パイプへ直接注入できます。省略した場合、コンポーネントレベルの自己注入は禁止されます(Black-Box パターン。内部の配線はすべて Recipe が担います)。セマンティクスは usesSchema[].inject と同じですが、コンポーネント間のトポロジーではなく、コンポーネント自身の values を管理します。all を除く任意のメカニズム名を列挙できます。all はどの inject ブロックでも指定できません。
usesSchemaobject のマップいいえこのエンティティが宣言する依存ソケットで、ソケット名をキーとします。ソケットを通じて張られる各接続は、そのソケットの宣言(セレクタ、許可する inject メカニズム、接続ごとの契約)に照らしてチェックされます。キー: 1 文字以上の英字、数字、アンダースコア、またはハイフン。ドットは使用できません。パターン: ^[a-zA-Z0-9_-]+$。
schemaanyいいえ自由形式のピラーを扱う JSON Schema 2020-12 の内容。values(Developer の領域。Developer が Aggregate 内で Component のインスタンスごとに設定する、アプリケーションの形状に関するパラメータ)、infra(Operator の領域。Release が供給する物理的なサイジングのノブ)、provides(この Component がトポロジーパイプを介してコンシューマーに公開する下流のコンテキストキー)です。内容の形状によるディスパッチで 4 つの記述モードを受け付けます。(1) インライン内容(コンパクト形式、JSON Schema YAML、またはその混在を含む YAML マップ)。(2) {$import: } によるファイル置換。spec.schema に記述すると 1 つのファイルから契約全体を供給し、単一のピラーに記述するとそのピラーのみを供給します。相対パスは、それを宣言したエンティティを含むディレクトリを基準に読み取られます。(3) {$ref: #/schemas/} による、ベア名の同一性で SchemaLibrary のエントリを指すドキュメント間参照(バージョンは Release ごとのロックファイルが供給し、参照にレジストリのホストは現れません)。(4) ベア文字列 inherited。これは extends を宣言する Component が記述できる唯一の形式で、3 つのピラーがベース Component から、ベースが記述したとおりに来ることを示します。モード 1〜3 は内容を記述するもので、extends を宣言しない Component でのみ使用できます。モード 4 は内容を記述せず、extends を宣言するすべての Component で必須です。付随するフィールド usesSchema と featuresSchema は固定形状のピラー(依存ソケット、アタッチメントスロット)を扱い、コンパイラがこの 3 つを、インスタンスの検証に使う 1 つのスキーマに合成します。
assertionsstring のマップいいえビルド時のフィールド間検証。各エントリは名前付きのアサーションです。キーはエラーメッセージに表示される安定したルール識別子で、値は {{ fail "message" }} による停止セマンティクスを持つ Go テンプレート文字列です。エンティティごとの複数の名前付きアサーションは、作成者が宣言した順序でインスタンスごとに評価され、最初に失敗したアサーションがビルドを停止します。Component のアサーションは、解決と静的解析の後、レンダリングの前に評価され、どの Recipe がバインドされるかにかかわらず成り立つ、契約のアーキテクチャ上の不変条件を表します。テンプレートコンテキスト: .values / .infra / .uses / .features / .metadata。評価器は missingkey=error を使用するため、未定義のキーへの参照は no-such-key 診断で停止します。素の参照はフォールバックが実行される前に停止するため、この面では単純な default では省略可能フィールドのフォールバックを供給できません。参照を hasKey でガードするか、存在チェックを直接行う optional ヘルパーを使用します。index でキーを読み取っても同様に供給できません。index はマップが持たないマップキーに対してそのキーを示して停止します。継承は加算的です。extends を宣言する Component は、自身のアサーションに加えて継承したアサーションに対しても評価され、継承したルールが先に評価されます。任意の深さのチェーンはチェーンのルートから下に向かって蓄積されるため、複数のルールが失敗する場合は、チェーンの最も上で宣言されたルールが報告されます。継承した名前を再利用して別のルールを宣言すると、extends チェーンがカタログに対して解決される時点で、両方の Components と共有された名前を示して拒否されます。そのため、拡張するドキュメント単体からではなく、ベース Component が存在した時点で表面化します。拡張する Component はルールを追加するのみで、置き換えることはありません。継承したルールを同じ名前でバイト単位で同一に再記述することは、何もしない操作として受け入れられます。2 つのルールが同時に成り立ち得るかどうかは何もチェックしません。相互に満たし得ないペアは記述上の誤りであり、事前の警告としてではなく、インスタンスがどちらか先に発火した方に引っかかったときに通常のアサーション失敗として表面化します。

追加のプロパティは許可されません。

定義

extending-component-must-declare-schema-inherited

spec.extends が存在する場合に適用されます。拡張する Component は、ベースの values / infra / provides をベースが記述したとおりに受け取るため、spec.schema: inherited を宣言し、ピラーの内容を独自に記述しません。それ以外の 2 つの結果はどちらもエラーであり、それぞれ異なる誤りです。spec.schema を完全に省略すると、継承されたピラーブロックと書き忘れたブロックを読み手が区別できなくなります。また、spec.schema の下にピラーの内容を記述すると、契約がベースの契約である Component に対して、異なる 2 つ目の契約を求めることになります。

プロパティ種類必須説明
schemaconst “inherited”はい継承マーカーであり、extends を宣言する Component で spec.schema が取る唯一の値です。ピラーの出どころを示すもので、ピラーの内容そのものはベース Component のものです。定数: "inherited"

non-extending-component-authors-its-own-schema

spec.extends が存在しない場合に適用されます。どのベースも拡張しない Component は、独自の values / infra / provides の内容を spec.schema の下に記述するため、このフィールドには継承マーカーではなく記述された内容が入ります。マーカーはピラーがベースから来ることを示しますが、この Component にはベースがありません。

プロパティ種類必須説明
schemaobjectいいえ記述されたピラーの内容。spec.schema が説明する 3 つの内容記述モードのいずれかによるマップです。