スキーマ駆動のデータ検証と保護

スキーマ駆動のデータ検証と保護

お知らせ：当社は、お客様により充実したサポート情報を迅速に提供するため、本ページのコンテンツは機械翻訳を用いて日本語に翻訳しています。正確かつ最新のサポート情報をご覧いただくには、本内容の英語版を参照してください。

Circuitは、実行の各段階で構造化された検証とデータ保護を適用するため、スキーマ駆動型アーキテクチャに従います。

Circuitでは、JSON Schemaを使用して以下を定義します。

  • 想定される項目とデータ型

  • 検証ルールと制約

  • 入力と出力の構造

  • 項目レベルのデータ保護ポリシー

これにより、一貫性があり、安全で、コンプライアンスに準拠したワークフロー処理が可能になります。

スキーマ検証レベル 

スキーマは2つのレベルで設定できます。

Circuitレベルのスキーマ

  • Circuit入力スキーマ：実行開始前に受信JSONを検証します。検証に失敗した場合、Circuitは開始されません。

ステートレベルのスキーマ

各ステートでは、以下に対応しています。

  • ステート入力スキーマ：ステートの実行前にステート入力JSONを検証します

  • ステート結果スキーマ：次のステートに渡す前にステート出力を検証します

検証に失敗した場合、ステートの実行は失敗し、エラーが実行ログに記録されます。

 

データ保護キーワード（主要なセキュリティ機能）

Circuitでは、標準のJSON Schemaを拡張し、プライバシー保護に重点を置いた組み込みキーワードを利用できます。これらは、深くネストされた項目を含む任意のプロパティに適用できます。

これらの制御は項目レベルで動作し、実行中に自動的に適用されます。

利用可能なデータ保護方法

hide: true  

  • APIレスポンスから項目を完全に削除します

  • 保護の優先度が最も高くなります

  • 内部システム項目や識別子に適しています

encrypt: true  

  • データベースに保存する前に値を暗号化します

  • RetryまたはRerun時のみ復号されます

  • 機密性の高い識別子、トークン、規制対象データを保護します

redact: true  

値を固定のプレースホルダー（例：[REDACTED]）に置き換えます。元の値は安全に保持され、監査ログには秘匿解除を実行したユーザーが記録されます。

  • 値を固定のプレースホルダー（例：[REDACTED]）に置き換えます

  • 元の値は安全に保持されます

  • 監査ログには、秘匿解除を実行したユーザーが記録されます

  • 厳格に保護すべきPIIや機密データに適しています 

mask: true  

  • 値を部分的に非表示にします（例：****）

  • 機密データを保護しながら、制御された表示設定を可能にします

同じ項目に複数の保護ルールが適用されている場合、以下の順序で適用されます。

非表示 → 暗号化 → 秘匿化 → マスク

これにより、複数のルールが設定されている場合でも、予測可能で安全な動作が確保されます。

保護の優先順位 

同じ項目に複数のデータ保護ルールが適用されている場合、以下の優先順位で適用されます。
非表示 → 暗号化 → 秘匿化 → マスク

保存時の暗号化（EAR）

すべての実行コンテキストデータは、保存時の暗号化によって保護されます。

  • 'encrypt': trueが指定された項目は、保存前に暗号化されます。

  • RetryまたはRerun時のみ復号されます。

  • アイドル状態および通常の実行状態でも、データは保護されたままです。

  • 実行コンテキストはワークフローインスタンスごとに分離されます。

このアーキテクチャにより、機密データが不要に公開されることを防ぎます。

スキーマプロパティの設定（UI）

ステップ1：入力スキーマの表示

Circuit全体に検証を適用するには、Circuit名の横にある［操作］メニュー（⋮）をクリックします。特定のステートのみに適用するには、ステート内の［操作］メニュー（⋮）をクリックし、［入力スキーマ］を選択します。

ステップ2：プロパティの追加

スキーマの作成方法を選択します。
  • ［新しいプロパティを追加］（手動）
    1. 対象の［プロパティ名］を入力します。
    2. 対象の［データ型］（string、number、integer、boolean、object、array）を選択します。
    3. 必要に応じて、プロパティを［必須］として指定します。 

  • JSONデータからのスキーマ生成（自動生成）

    1. コンバーターの左側にJSONペイロードを貼り付けると、対応するJSONスキーマが右側に自動的に表示されます。
    2. すでにJSONスキーマがある場合は、［空のスキーマを生成］をクリックして、右側に直接貼り付けます。
    3. スキーマからプロパティを自動生成するには、［スキーマを更新］をクリックします。
    4. 自動生成されたプロパティを確認します。
    5. 必要に応じて項目を追加するには、［プロパティを追加］をクリックします。
            

ステップ3：検証設定（任意）

プロパティ名の横にある展開アイコンをクリックして、次の追加の検証設定を行います。タイトルと説明

  • 最小値／最大値

  • 形式（例：メール）

  • 列挙値

  • 初期値

  • データ保護方法：非表示、暗号化、墨消し、マスク


初期値  

入力で項目が指定されておらず、スキーマに初期値が定義されている場合、処理を続行する前に、システムがその項目に初期値を自動的に割り当てます。

これにより、次のことが保証されます。

  • 不足している任意項目に、定義済みの値が設定されます

  • 入力が不足していても、ワークフローが中断されずに継続します

 

ステップ4：ネストされたプロパティの追加（任意）

プロパティのデータ型がオブジェクトの場合、その中にネストされたプロパティを追加できます。ネストされたプロパティでは、同じ検証ルールとデータ保護ルールがサポートされます。複数階層のネストにも対応しています。


ステップ5：変更の保存

  1. プロパティを追加した後、変更をクライアントレベルで適用するには、［保存］をクリックします。

  2. 保存済みのプロパティを変更するには、編集してから［更新］をクリックします。

  3. 既存のすべてのプロパティを破棄して最初からやり直すには、［リセット］をクリックします。

  4. 確定したら、スキーマをデータベースに保持するために、サーキットで［保存］をクリックします。


Notes

  • スキーマのプロパティパネル内の［保存］をクリックしても、変更はクライアントレベルにのみ適用されます。設定を永続的に保存するには、サーキットでも［保存］をクリックする必要があります。

  • 必須としてマークされたプロパティのみが、検証時に必須として扱われます。


スキーマ例     

この例では、最上位レベルでデータ保護が適用された従業員の主要項目を示します。

例1：データ保護を適用した基本プロパティ  

{
'type': 'object',
'required': ['employeeId', 'fullName', 'メール', 'department'],
'properties': {
'employeeId': { 'type': 'integer', 'title': 'Employee ID', 'mask': true },
'fullName': { 'type': 'string', 'title': 'Full Name' },
'メール': { 'type': 'string', 'title': 'Work メール', 'encrypt': true },
'department': { 'type': 'string', 'title': 'Department', 'redact': true },
'salary': { 'type': 'number', 'title': 'Annual Salary', 'redact': true }
}
}


入力例
 
{
'employeeId': '100423',
'fullName': 'Sarah Mitchell',
'department': 'Engineering',
'salary': '95000'
}
出力  
{
'employeeId': '######',
'fullName': 'Sarah Mitchell',
'メール': '[ENCRYPTED]',
'department': '[REDACTED]',
'salary': '[REDACTED]'
}


例2：入れ子プロパティ  （データ保護あり）

この例では、従業員データ内の入れ子オブジェクトとして個人情報を設定し、両方のレベルにデータ保護を適用しています。

{
'type': 'object',
'properties': {
'fullName': { 'type': 'string', 'title': 'Full Name' },
'メール': { 'type': 'string', 'title': 'Work メール', 'encrypt': true },
'personalDetails': {
'type': 'object',
'title': 'Personal Details',
'properties': {
'phone': { 'type': 'string', 'title': 'Phone Number', 'hide': true },
'address': { 'type': 'string', 'title': 'Home Address', 'redact': true }
}
}
}
}


入力例
 
{
'fullName': 'Sarah Mitchell',
'personalDetails': {
'phone': '+1-555-987-6543',
'address': '42 Maple Street, Austin, TX 78701'
}
}

}


出力
 
{
'fullName': 'Sarah Mitchell',
'メール': '[ENCRYPTED]',
'personalDetails': {
'address': '[REDACTED]'
}
}

トラブルシューティングFAQ：JSONスキーマ検証

1. サーキットが実行されない理由

もしサーキットレベルのスキーマ検証に失敗すると、実行は開始されません。

確認事項。

  • 必須項目

  • 入力データの構造

  • データ型


2. 実行前にステートが失敗する理由  

もしステート入力スキーマの検証に失敗すると、ステートは実行されません。

確認事項。

  • ステートに渡された入力

  • 入力パスの設定

  • 必須項目


3. 実行後にステートが失敗する理由  

もしステートの出力がスキーマと一致しない場合、次のステートにデータを渡す前に失敗します。

確認事項。

  • 出力の構造

  • 項目名と型

  • 結果パス


4. スキーマ検証に失敗した場合の動作  

  • サーキットレベルの失敗→実行は開始されません

  • ステート入力の失敗→ステートは実行されません

  • ステート出力の失敗→データを渡す前にステートが失敗します

すべての失敗はデバッグ用にログに記録されます。

5. サーキットレベルのスキーマとステートレベルのスキーマの違い  

  • サーキットレベルのスキーマ→実行開始前に入力を検証します

  • ステートレベルのスキーマ→各ステップでデータを検証します

これにより、失敗が発生した場所を特定できます。

6. 検証エラーの確認場所  

すべての検証エラーは実行ログで確認できます。

ログで確認できること。

  • 失敗した項目の特定

  • 不正なデータの追跡


7. 必須項目が不足している場合の動作  

  • 「必須」として設定されている場合→検証に失敗します

  • 「初期値」がある場合→自動的に適用されます


8. すべての項目が必須かどうか  

いいえ。「必須」として設定された項目のみが必須です。

​

9. データがスキーマと一致しない理由  

よくある問題。

  • データ型が正しくない

  • 必須項目が入力されていない

  • 形式または値が無効