author-governance-ruleset

API Governance ルールセット作成者

ガバナンス CLI ツールを使って、モデルの検出、検証、簡略化を行い、有効な Anypoint API Governance ルールセット（Validation Profile 1.0 YAML）を作成します。

概要

ガバナンスルールセットは、#%Validation Profile 1.0 で始まり、ドメインモデル（API 仕様、API インスタンス、MCP サーバーなど）に対する検証ルールを宣言する YAML ファイルです。各ルールはクラスを対象とし、そのプロパティに制約を設け、重要度（violation、warning、info）が割り当てられます。

このスキルでは、anypoint-cli-v4 governance:ruleset CLI コマンドを使ってモデルを検出し、ルールセットを検証して、出力を簡略化します。クラス名、プロパティ名、制約の互換性を推測してはいけません。必ず CLI に問い合わせてください。

---

前提条件：Governance Plugin のバージョンを確認する

ガバナンス CLI コマンドを実行する前に、最新のガバナンスプラグインを強制的にインストールし、このスキルで使うモデル、制約、検証ロジックを揃えてください。バージョン 1.0.20 以降が必要です。

anypoint-cli-v4 plugins:install mulesoft-anypoint-cli-governance-plugin@latest

プラグインがすでにインストールされているように見える場合でも、スキルを開始するたびにこれを実行してください。@latest により、互換性のあるバージョン（1.0.20 以降）が確実にインストールされます。この処理が正常に完了してから、以下の手順に進んでください。

ステップ 1：意図を把握する

ユーザーのリクエストを解析します。以下を特定してください。

• 対象となるクラス／ノード（例：Operation、WebAPI、APIInstance、MCPServer）
• 制約を適用するプロパティ（例：description、version、policies）
• 満たすべき条件（例：存在すること、パターンに一致すること、少なくとも 1 つ含むこと）

ユーザーがドメイン用語（例：「consumerUrl」、「endpointUrl」、「rate-limit policy」）を使っている場合は、次のコマンドで解決します。

anypoint-cli-v4 governance:ruleset:resolve <term>

エイリアスは作成時の補助にのみ使用します。ルールセット YAML に含めてはいけません。resolve コマンドが返す正規の targetClass と path を使用してください。

ステップ 2：ドメインを選ぶ

使用可能なドメインを一覧表示し、ユーザーの意図に合うものを選びます。

anypoint-cli-v4 governance:ruleset:domains

重要なルール： 1 つのルールセットで対象にできる specKind は 1 つだけです。api-spec と mcp の対象を同じルールセットに含めてはいけません。specKind のないドメインは自由に組み合わせられます。

ステップ 3：モデルを検出する

選択したドメインで対象にできるクラスを一覧表示します。

anypoint-cli-v4 governance:ruleset:classes --domain <domain-name>

次に、対象クラスのプロパティとその型を一覧表示します。

anypoint-cli-v4 governance:ruleset:properties <prefix.ClassName>

プロパティの型（scalar、node、scalarArray、nodeArray）によって、使用できる制約が決まります。

ステップ 4：制約を選ぶ

プロパティの型に対して有効な制約を問い合わせます。

anypoint-cli-v4 governance:ruleset:constraints --type <propertyType>

<propertyType> には、scalar、node、scalarArray、nodeArray のいずれかを指定します。

よくある間違い：

• nodeArray または node プロパティに pattern や in を使用しないでください
• nodeArray に atLeast／atMost を使用して、「条件 X に一致する項目が少なくとも 1 つある」ことを確認します
• scalarArray に containsSome を使用して、「値 X が少なくとも 1 つある」ことを確認します
• scalarArray に in を使用して、すべての値を許可された集合に制限します
• / を使うプロパティパスはネストされたノードをたどります。有効な制約は、最後のプロパティによって決まります

ステップ 5：ルールセットを作成する

有効な Validation Profile 1.0 YAML をファイルに書き込みます。

#%Validation Profile 1.0
profile: <profile-name>
prefixes:                    # Only needed for non-default namespaces
  management: http://anypoint.com/vocabs/management#
validations:
  <rule-name>:
    targetClass: <prefix.ClassName>
    message: <human-readable error message>
    propertyConstraints:
      <prefix.propertyName>:
        <constraint>: <value>
violation:                   # MUST assign every rule to a severity
  - <rule-name>
warning:
  - <other-rule>
info:
  - <another-rule>

デフォルトのプレフィックス（再宣言しないでください）：

• apiContract、core、shacl、shapes、raml-shapes、doc、meta、security、data、xsd、rdfs、rdf、sourcemaps

デフォルト以外のプレフィックス（prefixes: ブロックで宣言する必要があります）：

• management: http://anypoint.com/vocabs/management#
• mulesoft: http://anypoint.com/vocabs/management#mulesoft.com/
• gcl: http://anypoint.com/vocabs/gcl#
• api: http://anypoint.com/vocabs/api#
• catalog: http://anypoint.com/vocabs/digital-repository#
• mcp: http://anypoint.com/vocabs/mcp#
• apiExt: http://a.ml/vocabularies/api-extension#

ステップ 6：ルールセットを検証する

ルールセットを作成または変更した後、CLI で検証します：

anypoint-cli-v4 governance:ruleset:validate-authoring <path-to-ruleset.yaml>

次の項目を確認します：YAML 構文、JSON スキーマへの準拠、targetClass の有効性、プロパティパスの正確性、制約タイプの互換性、重大度の割り当て。

検証でエラーが返された場合は修正し、再検証してください。エラーが 0 件で検証に合格するまで、ルールセットをユーザーに提示してはいけません。

ステップ 7：簡素化する

検証に合格したら、ルールセットを簡素化します：

anypoint-cli-v4 governance:ruleset:simplify <path-to-ruleset.yaml>

これにより、ネストされたプロパティパスがフラット化され、冗長な論理ラッパーが削除されます。変更が加えられた場合は、簡素化された出力をファイルに書き戻し、再度検証してください。

ステップ 8：結果を提示する

検証済みで簡素化済みの最終的なルールセットをユーザーに提示します。次の内容を簡潔に説明します：

• 何をチェックするか
• どの制約を選んだか、またその理由
• 重大度の割り当て

---

ルール

• 必ず 1 行目を #%Validation Profile 1.0 で始める
• すべての検証に必ず重大度レベル（violation、warning、info）を割り当てる
• ルールセットの YAML ではエイリアスを絶対に使用せず、必ず canonical targetClass + プロパティパスを使用する
• 同じルールセットで api-spec のターゲットと mcp のターゲットを絶対に組み合わせない
• プロパティ名を絶対に推測せず、必ず governance:ruleset:properties <class> を実行して調べる
• 制約の互換性を絶対に推測せず、必ず governance:ruleset:constraints --type <type> を実行する
• 書き込みまたは変更のたびに、必ず governance:ruleset:validate-authoring で検証する
• 検証に合格したら、必ず governance:ruleset:simplify で簡素化する
• プロパティパスでは、セグメントの区切りに /（スペース、スラッシュ、スペース）を使用する
• 代替パスでは、( ) で囲んだ選択肢の間に |（スペース、パイプ、スペース）を使用する
• 条件付きルールでは、検証レベルで if: / then: を使用する
• 論理的な組み合わせでは、検証レベルで and:、or:、not:、または xone: を使用する
• Rego（rego:）はリソース間のチェックに限った最後の手段とし、宣言型制約を優先する
• メッセージテンプレートでは、プロパティ値を参照できます："{{ prefix.property }}"
• 既存のルールセットを変更する場合は、変更を適用した後に再検証する
• ユーザーからサポート対象ドメインについて尋ねられた場合は、governance:ruleset:domains を実行する。確認せずに非対応だと断言してはいけない