出力スキーマ

一部のノードでは、そのノードが出力する値に対して JSON スキーマ を定義できます。スキーマは、そのノードが返す JSON の形（たとえば instanceId と state を持つオブジェクトや、バケット名の配列など）を記述し、後続のノードがフィルター・条件・次のステップで個々のフィールドを参照できるようにします。たとえば、Code ノードが EC2 インスタンス ID と状態の一覧を返す場合、出力スキーマを定義しておくことで、後続の Filter ノードは state を参照して running のインスタンスだけを残したり、Notification ノードがメッセージ内に特定のフィールドを含めたりできます。スキーマを定義することで、スクリプトや CLI コマンド、LLM のレスポンスからの構造化された出力を、フロー全体で有効に活用できるようになります。

出力スキーマは、ノードのパラメータ内の Referencing the output で Advanced referencing を選択して設定します。次のノードで出力スキーマをサポートしています。

• Code node
• CLI node
• LLM node

スキーマを生成する

JSON スキーマを生成する際は、次のいずれかを行えます。

• AI によるスキーマ生成を使用する: ノードのパラメータから Suggest schema を選択し、プロンプトの内容に基づいて出力スキーマを自動推論・生成します。生成されたスキーマは後から編集できますが、必ずペイロードだけを記述していることを確認してください。

• 定義ルール と スキーマパターン を使って JSON スキーマを手動で記述する

スキーマの対象範囲

出力スキーマは、ノードのコードや設定から返される値そのもの、つまり他のノードが利用する実際のペイロードのみを記述します。実行ログや Test results タブに表示される実行メタデータやランタイムのラッパー（例: results, message, context）は対象外です。あくまで、ノードの機能的な出力だけを取り出して単独の JSON ドキュメントとして扱ったときに得られる値に対してスキーマを定義し、その周りのラッパーはモデル化しないでください。

定義ルール

出力スキーマを定義する際は、次の点に従ってください。

• トップレベルの型 を正確に一致させる: object, array, string, number, boolean, null のいずれか
• 形を 再帰的に 定義する:
  • object の場合は properties（必要に応じて required も）を定義する
  • array の場合は items（各要素のスキーマ）を定義する
• CloudFlow の予約済みフィールド（例: results, message, context）を参照しないこと。これらはランタイムのラッパーであり、ノードの機能的な出力ではありません。

注意

CloudFlow の出力スキーマは、完全な JSON Schema ドキュメントではありません。公式の JSON Schema のガイドでは、最小限のスキーマとして "$schema"（たとえば "https://json-schema.org/draft/2020-12/schema"。これは仕様バージョンを示します）や "$id"（スキーマ自体の URI）を含めることがよく説明されています。これはスタンドアロンのスキーマファイルとしては一般的なパターンです。

CloudFlow が想定しているのは、ノードの戻り値を記述する JSON オブジェクトのみであり、type、properties、items、required といったキーワードだけです。出力スキーマ欄には $schema（draft/2020-12 のメタスキーマ URL を含む）や $id を含めないでください。これらはサポートされておらず、スキーマが期待どおりに動作しない原因になります。

機微なフィールドのマーク

スキーマ内の特定のフィールドを sensitive としてマークし、その値を CloudFlow がシークレットとして扱うようにできます。プロパティに "sensitive": true が設定されている場合、CloudFlow はそのフィールドの値を保存時に暗号化し、CloudFlow UI やログでは必要に応じてマスクしつつ、実行時には後続ノードから参照できるようにします。

たとえば、入れ子になった key フィールドを機微情報としてマークするには、次のようにします。

{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "id": { "type": "integer" },
        "key": { "type": "string", "sensitive": true }
      }
    }
  }
}

"sensitive": true は、API キー、トークン、認証情報などのシークレットや機密値を含むフィールドにのみ使用し、CloudFlow が適切に保護できるようにしてください。

スキーマパターン

その他のペイロード形状には、次のパターンを使用してください。重要な点として、スキーマはペイロード（例: results[0] の中身）のみを記述し、実行時ラッパーは対象としません。

ノードがオブジェクトを返す場合:

{ "type": "object", "properties": { "foo": { "type": "string" } } }

ノードが配列を返す場合:

{ "type": "array", "items": { "type": "number" } }

ノードが入れ子のオブジェクトを返す場合:

{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "id": { "type": "integer" }
      }
    }
  }
}

ノードが必須フィールドを持つオブジェクトを返す場合:

{
  "type": "object",
  "properties": {
    "status": { "type": "string" },
    "count": { "type": "number" }
  },
  "required": ["status"]
}

例

例: Code ノードが EC2 インスタンスデータを返す場合

Code ノードがデータ（たとえばインスタンス ID と状態）を返すとき、実行出力には CloudFlow のラッパーが含まれます。出力スキーマは ペイロード だけ、つまり results[0] 内の値に対して定義します。

実行出力（簡略化。ラッパーには results, message, context が含まれます）:

[
  {
    "results": [
      {
        "instanceId": "i-0abc123",
        "state": "running"
      }
    ],
    "message": "OK",
    "context": {}
  }
]

後続ノードが参照する ペイロード は、results[0] 内のオブジェクトです。

{
  "instanceId": "i-0abc123",
  "state": "running"
}

定義すべき 出力スキーマ（ラッパーではなくペイロードのみを記述）:

{
  "type": "object",
  "properties": {
    "instanceId": { "type": "string" },
    "state": { "type": "string" }
  }
}

スキーマをテストする

スキーマをテストするには、ノードを実行するか保存済みのテストデータを使用して、出力を取得できるようにしてください。スキーマがペイロードと一致していること、そして後続ノードが必要なフィールドを参照できることを確認してください。ノードの実行方法、テストデータの保存方法、および後続ノードのテスト方法については、Test nodes を参照してください。

関連情報

• Nodes
• Code node
• CLI node
• LLM node