Policy JSON Schema

ポリシーは、PII-Fi APIの検出・マスキング動作をカスタマイズするための設定オブジェクトです。どのエンティティタイプを検出するか、各エンティティをどう処理するかを細かく制御できます。

基本的な使い方

最もシンプルなケースでは、エンティティの有効/無効のみを指定します。

{
  "policy": {
    "version": "2.0",
    "entities": {
      "name": {"enabled": true},
      "phone": {"enabled": true},
      "email": {"enabled": false}
    }
  }
}

指定しなかったエンティティはデフォルトポリシーの設定が適用されます。 enabled: false を明示的に指定することで検出を無効化できます。

完全なスキーマ

ポリシーJSONの完全な構造は以下の通りです。

{
  "version": "2.0",
  "name": "my_policy",
  "description": "カスタムポリシーの説明",

  "entities": {
    "name": {
      "enabled": true,
      "entity_type": "JPII_PERSON_NAME",
      "category": "personal",
      "description": "人名",
      "display": {
        "label_ja": "人名",
        "label_en": "Person Name"
      },
      "detection": {
        "min_length": 2,
        "methods": {
          "pattern_match": {"enabled": true, "priority": 85},
          "ner": {"enabled": true, "priority": 98}
        }
      },
      "deidentification": {
        "replace_text": "<人名>",
        "mask_char": "●",
        "faker_type": "name"
      }
    }
  },

  "filters": {
    "allow_list": ["本社", "支社", ...],
    "confidence_threshold": 0.5
  },

  "detector_config": {
    "confidence_threshold": 0.5,
    "context_enhancement_enabled": true
  }
}

トップレベルフィールド

Field	Type	Description
`version`	string	ポリシースキーマのバージョン（`"2.0"`）
`name`	string	ポリシーの識別名
`description`	string	ポリシーの説明
`entities`	object	エンティティタイプごとの検出・マスキング設定
`filters`	object	検出結果のフィルタリング設定
`detector_config`	object	検出器の動作設定

entities

entities オブジェクトでは、各エンティティタイプの検出・マスキングを設定します。

利用可能なエンティティキー

Key	Entity Type	デフォルトpriority	Description
`name`	JPII_PERSON_NAME	pattern: 85, ner: 98	人名
`phone`	JPII_PHONE_NUMBER	110	電話番号
`email`	JPII_EMAIL_ADDRESS	120	メールアドレス
`organization`	JPII_ORGANIZATION	pattern: 85, ner: 95	組織名・会社名
`address`	JPII_ADDRESS	pattern: 85, ner: 95	住所
`date`	JPII_DATE	85	日付
`financial`	JPII_FINANCIAL_INFO	100	金融・識別情報（マイナンバー等）
`credit_card`	JPII_CREDIT_CARD	80	クレジットカード番号
`ip_address`	JPII_IP_ADDRESS	80	IPアドレス
`url`	JPII_URL	105	URL
`business_info`	JPII_BUSINESS_INFO	80	ビジネス情報

文脈解析パイプライン出力エンティティ

Key	Entity Type	Description
`financial_personal_income`	JPII_PERSONAL_INCOME	個人収入
`financial_corporate_earnings`	JPII_CORPORATE_EARNINGS	企業業績
`financial_corporate_strategic`	JPII_CORPORATE_STRATEGIC	戦略的財務情報
`financial_hr_compensation`	JPII_HR_COMPENSATION	人事報酬
`financial_transaction`	JPII_TRANSACTION	取引・契約

検出設定（detection）

各エンティティの検出方法を細かく制御できます。

Field	Type	Description
`min_length`	integer	この文字数未満の検出結果は除外
`methods`	object	検出方法の設定

methods

検出方法には以下の種類があります。

Method	Description
`pattern_match`	正規表現パターンによる検出
`ner`	NER（機械学習でトレーニングされたTransformerベースの固有表現抽出器）による検出
`dictionary`	辞書マッチングによる検出
`contextual_pipeline`	文脈解析パイプラインによる検出

methodsの設定例

"detection": {
  "min_length": 2,
  "methods": {
    "pattern_match": {
      "enabled": true,
      "priority": 85
    },
    "ner": {
      "enabled": true,
      "priority": 98
    },
    "dictionary": {
      "enabled": true,
      "priority": 100,
      "dictionary_file": "dictionaries/companies.json"
    }
  }
}

priorityチューニング

💡 重要なユースケース

priority の調整は、検出結果を最適化するための最も一般的な方法です。同じ位置で複数の認識器が検出した場合、高いpriorityを持つ結果が採用されます。

priorityの動作原理

数値が大きいほど優先される
同じテキスト範囲で複数の検出があった場合、最も高いpriorityの結果を採用
デフォルト値は認識器タイプによって異なる（pattern: 80〜85、ner: 95〜98、dictionary: 100）

シナリオ1: NERより辞書を優先

会社名辞書を登録したが、NERの結果に上書きされてしまう場合。辞書のpriorityをNER（95）より高く設定します。

{
  "entities": {
    "organization": {
      "enabled": true,
      "detection": {
        "methods": {
          "ner": {"enabled": true, "priority": 95},
          "dictionary": {
            "enabled": true,
            "priority": 110,
            "dictionary_file": "dictionaries/companies.json"
          }
        }
      }
    }
  }
}

シナリオ2: パターンマッチの誤検出を抑制

パターンマッチで誤検出が多い場合、priorityを下げてNERを優先させます。

{
  "entities": {
    "name": {
      "enabled": true,
      "detection": {
        "methods": {
          "pattern_match": {"enabled": true, "priority": 70},
          "ner": {"enabled": true, "priority": 98}
        }
      }
    }
  }
}

シナリオ3: カスタム認識器を最優先

社員番号など独自パターンを最優先で検出したい場合。

{
  "entities": {
    "employee_id": {
      "enabled": true,
      "entity_type": "JPII_EMPLOYEE_ID",
      "detection": {
        "methods": {
          "pattern_match": {
            "enabled": true,
            "priority": 150
          }
        }
      }
    }
  }
}

推奨priority値

用途	推奨priority
最優先（カスタム認識器、重要な辞書）	120〜150
辞書マッチング（通常）	100〜110
NER（固有表現抽出）	95〜98
パターンマッチ（通常）	80〜90
補助的な検出（誤検出が多いもの）	60〜75

マスキング設定（deidentification）

各非識別化方式での出力をカスタマイズできます。

Field	Type	Description
`replace_text`	string	replace方式での置換文字列（例: `<人名>`）
`mask_char`	string	mask方式でのマスク文字（例: `●`、`*`）
`faker_type`	string	fake方式でのダミーデータタイプ（name, phone, email, address, company）
`faker_lists`	array	fake方式で使用する独自ダミー値リスト

カスタムマスキングの例

{
  "entities": {
    "name": {
      "enabled": true,
      "deidentification": {
        "replace_text": "[氏名]",
        "mask_char": "X"
      }
    },
    "credit_card": {
      "enabled": true,
      "deidentification": {
        "replace_text": "<カード番号>",
        "mask_char": "*",
        "faker_lists": [
          "4111-1111-1111-1111",
          "5500-0000-0000-0004"
        ]
      }
    }
  }
}

filters

検出結果のフィルタリング設定です。誤検出の抑制に有効です。

Field	Type	Description
`allow_list`	array	検出から除外する単語リスト（誤検出防止）
`exclude_digits_only`	array	数字のみの検出を除外するエンティティタイプ

誤検出を防ぐallow_list

「本社」「部長」などの一般的な単語が人名や組織名として誤検出される場合に有効です。

{
  "filters": {
    "allow_list": [
      "本社", "支社", "営業所", "事務所", "工場", "研究所",
      "社長", "部長", "課長", "係長", "主任",
      "顧客", "担当者", "責任者", "管理者",
      "製品", "サービス", "システム", "プロジェクト"
    ]
  }
}

detector_config

検出器の動作設定です。

Field	Type	Default	Description
`confidence_threshold`	float	0.5	この信頼度未満の検出結果は除外
`context_enhancement_enabled`	boolean	true	コンテキストキーワードによる信頼度補正
`cache_enabled`	boolean	true	検出結果キャッシュを有効化
`cache_ttl`	integer	3600	キャッシュの有効期限（秒）

厳格な検出（低い信頼度も採用）

{
  "detector_config": {
    "confidence_threshold": 0.3,
    "context_enhancement_enabled": true
  }
}

実用例

コールセンター向け（メール無効、人名・電話重視）

{
  "version": "2.0",
  "name": "call_center",
  "description": "コールセンター向けポリシー",
  "entities": {
    "name": {"enabled": true},
    "phone": {"enabled": true},
    "address": {"enabled": true},
    "email": {"enabled": false}
  },
  "filters": {
    "allow_list": ["お客様", "担当者", "オペレーター"]
  }
}

金融業向け（高セキュリティ、文脈解析有効）

{
  "version": "2.0",
  "name": "financial_strict",
  "description": "金融機関向け厳格ポリシー",
  "entities": {
    "name": {"enabled": true},
    "phone": {"enabled": true},
    "email": {"enabled": true},
    "address": {"enabled": true},
    "financial": {"enabled": true},
    "credit_card": {"enabled": true},
    "financial_personal_income": {"enabled": true},
    "financial_personal_asset": {"enabled": true},
    "financial_corporate_strategic": {"enabled": true}
  },
  "detector_config": {
    "confidence_threshold": 0.3
  }
}

社内辞書優先（取引先名を確実に検出）

{
  "version": "2.0",
  "name": "dictionary_priority",
  "entities": {
    "organization": {
      "enabled": true,
      "detection": {
        "methods": {
          "dictionary": {
            "enabled": true,
            "priority": 120,
            "dictionary_file": "dictionaries/partners.json"
          },
          "ner": {"enabled": true, "priority": 95}
        }
      }
    }
  }
}

ETag/If-Match（楽観的ロック）

ポリシーの作成・更新・削除には、楽観的ロックが必要です。

# Step 1: ETagを取得
ETAG=$(curl -s -I https://api.pii-fi.com/api/policy/active \
  -H "Authorization: Bearer YOUR_API_KEY" | grep -i etag | awk '{print $2}' | tr -d '\r')

# Step 2: ポリシーを作成
curl -X PUT https://api.pii-fi.com/api/policy/named/my_policy \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "If-Match: $ETAG" \
  -d '{
    "policy": {
      "version": "2.0",
      "entities": {
        "name": {"enabled": true},
        "email": {"enabled": false}
      }
    }
  }'

API Endpoints

Method	Endpoint	Description
GET	`/api/policy/list`	ポリシー一覧を取得
GET	`/api/policy/active`	アクティブなポリシー名を取得
GET	`/api/policy/named/{name}`	指定したポリシーの詳細を取得
PUT	`/api/policy/named/{name}`	ポリシーを作成または更新
DELETE	`/api/policy/named/{name}`	ポリシーを削除
POST	`/api/policy/activate/{name}`	ポリシーをアクティブ化

Next Steps

📖 Policy API Reference 📋 Entity Types 📝 Sample Code ⚙ Custom Recognizer