platform-policy-rule-generate

ポリシールール定義の作成ポリシー

ゲーティング： EnforceOMatic と PolicyRuleMDAPI の組織権限が必要です。
最小 API バージョン： 64.0（PolicyJsonExpression を使う条件では 66.0）。

このスキルでは、ポリシーを作成するためのディスク上のメタデータ XML 形式を扱います。*.policyRuleDefinition または *.policyRuleDefinitionSet ファイルの作成を求められた場合や、これらを含むメタデータパッケージを配布する場合に使用してください。ランタイム側（RuleProvider、フック）は対象外です。

---

評価範囲： このスキルは、スキルディレクトリ配下の tests/evals/ ではなく、チームの ADK 評価フレームワークによって評価されます。ACCESS／GOVERNANCE／RECORD／TRANSFORM の各バリアントを網羅する 5 つのデータセットは、packages/adk-eval/eval/domains/platform-policy-rule-generate/datasets/ にあります。

1. パッケージのレイアウト

デプロイ可能なパッケージには、常に以下が含まれます。

<fixture>/
  package.xml
  policyRuleDefinitionSets/<setName>.policyRuleDefinitionSet
  policyRuleDefinitions/<ruleName>.policyRuleDefinition

package.xml のテンプレート（ftest には <version>[ftest]</version> を、実際の組織には 64.0 以上を使用してください）。

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Rule0</members>
        <name>PolicyRuleDefinition</name>
    </types>
    <types>
        <members>Set1</members>
        <name>PolicyRuleDefinitionSet</name>
    </types>
    <version>64.0</version>
</Package>

---

2. PolicyRuleDefinitionSet スキーマ

<PolicyRuleDefinitionSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <label>Set1</label>
    <description>Optional free text</description>
    <replicated>false</replicated>             
    <builderCompatible>true</builderCompatible> 
    
</PolicyRuleDefinitionSet>

要素	必須	備考
<label>	はい	マスターラベル。ファイルのベース名（devName）が MDAPI 識別子であり、ラベルではありません。
<description>	いいえ	自由記述です。
<replicated>	いいえ	true にすると、関連する組織間でプレースホルダーが変換されます。null／false の場合は省略します。
<builderCompatible>	いいえ	true = §7 のチェックリストに従ってルールが監査されています。false = API 専用です。省略 = 未監査です。情報提供のみで、デプロイやランタイムには影響しません。
<builderValidated>	いいえ	サーバーによって管理されます。作成する XML には設定しないでください。 検証時にサーバーが上書きします。

---

3. PolicyRuleDefinition — コアフィールド

要素	必須	備考
<label>	はい	MasterLabel。
<category>	はい	§4 を参照してください。resourceScopeType と、policyRuleResourceDomains／resourceTransform が必須かどうかを決定します。TRANSFORM 以外では effect を制約しません。
<effect>	はい	Permit、Forbid、または Transform。コアで適用される唯一のカテゴリ連動ルールは effect=Transform ↔ category=TRANSFORM_POLICY_RULE_DEFINITION（双方向）です。それ以外のすべてのカテゴリでは、Permit と Forbid のどちらも使用できます。
<action>	はい（1 つ以上）	Read、TupleRead、Create など。複数の要素は OR 条件で結合されます。
<policyRuleDefinitionSetName>	はい	親セットの開発者名。
<principalScopeType>	はい	常に ANY です。
<resourceScopeType>	はい	ANY、FIELD、RECORD、DATASPACE、または SPAN。カテゴリと一致している必要があります（§4）。
<principalAuthenticationLevel>	いいえ	INTERNAL、AUTHENTICATED、UNIDENTIFIED、IDENTIFIED。
<ruleConsumer>	いいえ	ALL、DATACLOUD、MULESOFT、TABLEAU、CORE。
<policyRuleResourceDomains>	いいえ	RECORD（RLS）および FIELD スコープの TRANSFORM ルールでのみ必須です。ACCESS／GOVERNANCE では使用できません。
<resourceTransform>	いいえ	category=TRANSFORM の場合に必須であり、それ以外では有効ではありません。
<whenPolicyRuleDefinitionClauseConjunction>	いいえ	WHEN 条件。
<unlessPolicyRuleDefinitionClauseConjunction>	いいえ	UNLESS 条件。UI では編集できないため、WHEN と否定演算子の使用を推奨します。

---

4. カテゴリの決定ツリー

カテゴリはドメイン（プラットフォームのどの適用レイヤーでルールが適用されるか）を表します。エフェクトはアクション（許可／拒否／変換）を表します。TRANSFORM を除き、両者は独立しています。

プラットフォームが検証するカテゴリ × エフェクトのルールは、次の 1 つだけです。

• effect=Transform ⇔ category=TRANSFORM_POLICY_RULE_DEFINITION（双方向。不一致の場合は INVALIDFORCATEGORY がスローされます）。
• その他すべてのカテゴリ（ACCESS、GOVERNANCE、RECORD、IDENTIFIED_RECORD）では、Permit と Forbid のどちらも使用できます。

プラットフォームの自動入力のデフォルトに関する注意： 作成する XML で <category> を省略すると、サーバーは effect に基づいて値を入力します。Permit→ACCESS、Forbid→GOVERNANCE、Transform→TRANSFORM となります。これはデフォルト値の入力であり、検証ではありません。 明示的に指定したカテゴリがこのデフォルトと矛盾していても、そのまま受け入れられ、保存されます。

カテゴリの選択

What kind of policy?
│
├── OLS/FLS allow/deny on tagged or classified resources
│     category = ACCESS_POLICY_RULE_DEFINITION (allow/deny attestation in the access plane)
│              | GOVERNANCE_POLICY_RULE_DEFINITION (governance-audited)
│     effect = Permit | Forbid (chosen independently from category)
│     resourceScopeType = ANY | FIELD | DATASPACE
│     NO <policyRuleResourceDomains>
│     condition: resourcePath=TAG|CLASSIFICATION CONTAINS_ANY <ref>
│     For "objects AND all their fields" → action=TupleRead + OR-of-ENTITYTYPE clause (§7)
│     Note: "Block access to Foo object" → tag Foo with <yourTag>, write rule on tag
│        Do NOT use <resourceDomain>Foo</resourceDomain> — forbidden for ACCESS/GOVERNANCE
│
├── Row-level filter on a DMO/DLO
│     category = RECORD_POLICY_RULE_DEFINITION
│     effect = Permit | Forbid
│     resourceScopeType = RECORD
│     <policyRuleResourceDomains> = the DMO/DLO API name  ← entity targeting allowed here
│
├── Identified-Guest record access
│     NOT authorable via MDAPI — SESSION_CONSUMER_ID is not in RuleContextPathType
│        Must be implemented as a runtime RuleProvider.
│
└── Field masking
      category = TRANSFORM_POLICY_RULE_DEFINITION   ← required by RuleBuilder validator
      effect = Transform                            ← required by RuleBuilder validator
      resourceScopeType = FIELD (structured) or SPAN (unstructured)
      <policyRuleResourceDomains> = the DMO whose field is masked
      <resourceTransform> required (e.g. NULL_RESOURCE_TRANSFORM, LAST_N_CHARS_RESOURCE_TRANSFORM)

ACCESS と GOVERNANCE — 選び方

どちらも Permit と Forbid を合法的に受け付けます。どの適用レイヤーでルールを記録・監査するべきか、そしてプロンプトが文字どおり何を求めているかに基づいて選択してください。

ユースケース	選択	理由
プロンプトで「ACCESS policy rule」／「access rule」／「OLS/FLS」が明示されている	ACCESS_POLICY_RULE_DEFINITION	プロンプトの用語に一致し、データアクセスの適用レイヤーに属します。
プロンプトで「governance」／「audit」／「policy framework」／データレジデンシーやコンプライアンスに関する表現が使われている	GOVERNANCE_POLICY_RULE_DEFINITION	プロンプトの用語に一致し、ルールがガバナンスのレポートに表示されます。
プロンプトが曖昧で、許可／拒否の意味だけを説明している	Permit には ACCESS、Forbid には GOVERNANCE をデフォルトで選択します（プラットフォームの自動入力のデフォルトを反映したもので、安全にデプロイできますが、必須ではありません）

重要 — プロンプトで明示されたカテゴリに従ってください。 プロンプトに「ACCESS policy rule that denies …」または「GOVERNANCE policy rule that permits …」とある場合は、必ずそのカテゴリを出力してください。効果が Forbid（または Permit）だからといって、自動入力のデフォルトに黙って切り替えてはいけません。プラットフォームはどちらも受け付けます。エージェントは、ユーザーが明示した意図を上書きしてはいけません。

スコープ × カテゴリの互換性 — 次の表にない組み合わせはすべて INVALIDFORCATEGORY を返します。

	ACCESS	GOVERNANCE	TRANSFORM	RECORD
ANY	はい	はい	いいえ	いいえ
DATASPACE	はい	はい	いいえ	いいえ
FIELD	はい	はい	はい	いいえ
RECORD	いいえ	いいえ	いいえ	はい
SPAN	いいえ	いいえ	はい	いいえ

---

5. 条件パターン（クイックリファレンス）

すべての <conditions> ブロックには、次の4つすべてが必要です。<clause>、<operator>、1つのパス要素、値。

目的	パス要素	演算子	値
リソースがタグを持つ	<resourcePath>TAG</resourcePath>	CONTAINS_ANY	<valueReferenceType>CUSTOM_TAG | STANDARD_TAG</valueReferenceType>
リソースが分類を持つ	<resourcePath>CLASSIFICATION</resourcePath>	CONTAINS_ANY	CUSTOM_CLASSIFICATION | STANDARD_CLASSIFICATION
プリンシパルが権限を持つ	<principalPath>ASSIGNED_PERMISSIONS_PATH</principalPath>	CONTAINS_ANY | CONTAINS_NONE	<valueReferenceType>CUSTOM_PERMISSION</valueReferenceType>
セッションがデータスペース内にある	<contextPath>SESSION_DATASPACE</contextPath>	CONTAINS_ANY	<valueReferenceType>DATASPACE</valueReferenceType>
レコードフィールド = ユーザー属性	<resourcePath>RECORDFIELD</resourcePath> + <valueDomain>Schema:field</valueDomain>	EQUALS	<valuePrincipalPath>USER_ID | ORGANIZATION_ID | USER_ROLE_ID</valuePrincipalPath>
エンティティタイプのチェック	<resourcePath>ENTITYTYPE</resourcePath>	IS	<valueString>{"t":"Text","v":"FIELD"}</valueString>

<conjunctionExpression> は1始まりの前置記法です。1、(AND 1 2)、(OR 1 2)、(AND (OR 1 2) (AND 3)) のように記述します。トップレベルに単独のインデックス（1 など）を指定するのは、デプロイには有効ですが、Data Governance Policy Builder UI をクラッシュさせます。UIでの編集が必要な場合は、§7を参照してください。

パスの全列挙型（RulePrincipalPathType、RuleResourcePathType、RuleContextPathType）、演算子、JSON式（PROJECTION / ARGLIST / SOQLTARGETLISTEXPR）については、references/policy-schema-full.mdを参照してください。
すべてのポリシー種別のコピー＆ペースト用テンプレートについては、references/templates.mdを参照してください。

---

6. 検証ガードレール

1. すべての <conditions> には <operator> が必要です。欠落している場合は拒否されます。
2. すべての <conditions> には、少なくとも1つのパス要素（<resourcePath>、<principalPath>、<contextPath>、または <valueDomain>）が必要です。
3. <contextPath> に指定できるのは SESSION_DATASPACE のみです。リソースパスの値を指定してはいけません。
4. スコープ × カテゴリの組み合わせは、§4 のマトリックスに含まれている必要があります。よくある違反例：ACCESS/GOVERNANCE + RECORD スコープ、RECORD + ANY/FIELD スコープ、TRANSFORM + ANY/RECORD スコープ。（TRANSFORM を除き、効果はカテゴリに依存しません。§4 を参照してください。）
5. <resourceTransform> と effect=Transform は連動します。Transform 効果には <resourceTransform> が必要です。Permit/Forbid に <resourceTransform> を指定してはいけません。
6. <policyRuleResourceDomains> は、RECORD（RLS）および FIELD スコープの TRANSFORM では必須です。ACCESS/GOVERNANCE では指定できません。
7. <conjunctionExpression> のインデックスは、実際の <conditions> の数と一致している必要があります。1つでもずれていると拒否されます。
8. <conditions> 内の <clause> は、ラッパーと一致している必要があります（<when…> 内では WHEN、<unless…> 内では UNLESS）。
9. <valueString> 内の JSON リテラルでは、" を " にエスケープする必要があります。エスケープが誤っていると、リテラルが気づかれないまま破損します。
10. 参照先（<valueReference>、<resourceDomain>）は、デプロイ時にターゲット組織に存在している必要があります。
11. SCALAR_ATTRIBUTE / PLURAL_ATTRIBUTE は RulePrincipalPathType に含まれていません（MDAPI コントラクト外です）。こうした形式にはランタイムの RuleProvider を使用してください。
12. IDENTIFIED_RECORD は MDAPI では作成できません。SESSION_CONSUMER_ID は RuleContextPathType に含まれていません。
13. 標準タグ／分類の開発名は、完全修飾されたドット区切りのパスです（例：DataGovernanceTags.ExternalData.Visibility.Public）。作成する前に既存のルールを取得し、正確な文字列を確認してください。
14. 最小 API バージョン：PolicyRuleDefinition = 64.0、PolicyJsonExpression の条件 = 66.0、<replicated> = 260+、<builderCompatible> / <builderValidated> = 262+。

<conjunctionExpression> の形式に関する注意： トップレベルのインデックスを単独で指定しても（例：<conjunctionExpression>1</conjunctionExpression>）、デプロイは正常に完了します。サーバー側パーサーは、トップレベルのトークン単独指定を受け付けます。これはデプロイ時の検証エラーではありません。ただし、Data Governance Policy Builder の UI は読み込み時にクラッシュします。§7 を参照してください。

---

7. UI 互換性 — コア規則

Data Governance Policy Builder は、MDAPI の厳密なサブセットを編集します。デフォルトの目標は、UI 互換のポリシーを作成することです。API 専用の XML を作成する前に、必ずオペレーターに確認してください。

重大なブロッカー — 以下のいずれかに該当すると、ポリシーを編集できなくなります（また、いくつかはビルダーの読み込み時にクラッシュを引き起こします）。

• ACCESS/GOVERNANCE ルールに OR-of-ENTITYTYPE 句がない → 致命的なクラッシュ：Cannot use 'in' operator to search for 'Permit' in undefined。TupleRead と組み合わせる場合（実行時には機能的に冗長です）でも必須です。{"t":"Text","v":"OBJECT"} と {"t":"Text","v":"FIELD"} に対する IS 条件を含める必要があります。
• <conjunctionExpression> 内のトップレベル条件インデックスのみ（例：1、または (AND (OR 1 2) 3)）→ buildCriteria でビルダーの読み込み時にクラッシュします。デプロイには影響しませんが、UI ではポリシーを編集できません。必ずラップしてください。単一の条件には (AND 1) を使用し、(AND (OR 1 2) 3) の代わりに (AND (OR 1 2) (AND 3)) を使用してください。
• category = ACCESS_POLICY_RULE_DEFINITION + effect = Forbid → Data Governance Policy Builder UI（MDAPI ではありません）は、保存時にこれを GOVERNANCE に変換します。ビルダー経由のラウンドトリップでは、category が書き換えられます。MDAPI のデプロイには影響しません。元の ACCESS+Forbid の組み合わせは有効で、変更なしでデプロイされます。UI 経由のラウンドトリップが目的の場合は Forbid に GOVERNANCE を推奨します。信頼できる情報源が MDAPI の場合は、ACCESS+Forbid で問題ありません。
• <unlessPolicyRuleDefinitionClauseConjunction> ブロックがある → UI で最初に保存すると、警告なしに破棄されます。
• <action> が複数ある → 最初のものだけが保持されます。
• ruleConsumer ≠ DATACLOUD → UI は保存時に DATACLOUD をハードコードします。
• トップレベルの (OR 1 2) 句 → // ERROR: Unsupported rule! の経路が実行され、ルールが警告なしに破棄されます。

UI 互換の「unless」書き換え：

作成者の意図	UI 互換の形式
unless principal has permission X	WHEN ASSIGNED_PERMISSIONS_PATH CONTAINS_NONE X
unless resource has tag X	WHEN TAG CONTAINS_NONE X
unless record field = value	WHEN RECORDFIELD NOT_EQUALS value

UI 互換性チェックリスト、ラウンドトリップ規則、演算子のサポートマトリックス全体については、references/ui-compatibility.md を参照してください。

---

8. 作成ワークフロー

1. 最も近いテンプレートから始めます references/templates.md を参照し、そこから変更してください。空の状態から始めないでください。
2. 最初にカテゴリを選びます（§4）。カテゴリによって、effect、resourceScopeType、および policyRuleResourceDomains／resourceTransform が必須かどうかが決まります。
3. 基本ルールを配置します：トップレベルのフィールドのみを使い、条件は含めません。references/templates.md のカテゴリ別テンプレートに合わせてください。
4. 条件を1つずつ追加します。各条件には、<clause>、<operator>、パス要素1つ、値の4つをすべて指定してください。
5. <conjunctionExpression> を更新します：インデックスは1から始まる前置記法です。トップレベルのインデックス単独（例：1）でもデプロイできますが、UI が動作しなくなります。UI で編集する必要がある場合は (AND 1) のように囲んでください（§7）。
6. UI 互換性を確認します（§7／references/ui-compatibility.md）。該当する項目があれば、まず「unless」形式への書き換えを試みてください。それができない場合は、続行する前にオペレーターの明示的な確認を得てください。
7. package.xml を更新します：両方の型について、それぞれの <members> を記載してください。
8. §7 のチェックリストに合格した場合は、セットの <builderCompatible> を true に設定します。意図的に API のみで使用する場合は false に設定します。
9. 完了とする前に、§6（ガードレール）に照らして整合性を確認します。
10. 永続的な組織へのドライラン以外のデプロイを行う前に、ドライランで検証します。エラーがあれば、references/deploy-errors.md のエラーリファレンスを使って提示してください。

完了前に、次の3層で正しさを確認してください：

• 実行時の適用 — ルールは意図したとおりに適用されますか？（アクションの選択、条件の形）
• MDAPI デプロイの有効性 — デプロイできますか？（§6 のガードレール、スコープ×カテゴリ、タグの開発名、組織の権限）
• UI での編集可能性 — ビルダーで表示し、再保存できますか？（§7 のチェックリスト、OR-of-ENTITYTYPE 要件）

---

9. 出力の衛生管理 — エージェントがユーザーに伝えてはならないこと

エージェントがユーザー向けに返すチャット応答は、生成されるすべてのファイルに添えられます。お客様に内部エンジンや実装の詳細を見せてはなりません。

• ユーザー向けのテキストで内部評価エンジンの名前を挙げてはなりません。これには Cedar、policy engine、AuthZ engine、evaluation engine、Rego、OPA などが含まれますが、これらに限りません。お客様向けの表示では Data Governance、Policy Builder、Data Cloud Governance を使用し、それらの用語だけを使ってください。
• 評価の流れ、プリンシパルとリソースの照合セマンティクス、またはエンジン内部での条件の順序を説明する、末尾の「実行時の仕組み」的な説明を出力してはなりません。生成されたファイルが成果物です。デプロイした内容を1行で要約すれば十分です。ユーザーから適用の仕組みについて明示的に尋ねられた場合は、製品の用語で説明してください（例：「Data Governance は……の場合に読み取りを拒否します」）。エンジンの用語は決して使わないでください。
• ユーザー向けのテキストで内部パッケージ、ソースディレクトリ、Java クラス名、メソッド名、行番号への参照を挙げてはなりません。内部実装の識別子はお客様向けではありません。プラットフォームの動作は製品の用語のみで説明してください（「サーバーが……を検証します」「Data Governance が……を拒否します」）。
• ユーザーから求められない限り、自動入力／デフォルト入力／フォールバックのセマンティクスを説明してはなりません。ルールを提供し、ユーザーが次に行う必要のある作業に影響する場合に限り、制約を提示してください（例：「デプロイ前に DMO タグが存在している必要があります」）。

ユーザーがより詳しい説明を必要とする場合は、尋ねられたときに製品の用語で回答してください。

リファレンスドキュメント

詳細	ファイル
パス列挙型、演算子、値セット、JSON 式（PROJECTION / ARGLIST / SOQLTARGETLISTEXPR）の完全版	references/policy-schema-full.md
コピーして使えるテンプレート — インデックスは references/templates.md、バリアント別テンプレート：templates-access.md、templates-record.md、templates-transform.md、templates-advanced.md
UI 互換性チェックリストの完全版、ラウンドトリップのルール、演算子／パスのサポートマトリックス	references/ui-compatibility.md