Skip to main content

Output schema

Some nodes let you define a JSON schema for the node's output. The schema describes the shape of the JSON your node returns—for example, an object with instanceId and state, or an array of bucket names—so that downstream nodes can reference individual fields in filters, conditions, or the next step. For example, a Code node might return a list of EC2 instance IDs and states; with an output schema, a downstream Filter node can reference state to keep only running instances, or a Notification node can include specific fields in the message. Defining a schema makes structured output from scripts, CLI commands, or LLM responses usable across the rest of your flow.

You configure an output schema by choosing Advanced referencing under Referencing the output in the node's parameters. The following nodes support output schema:

Generate your schema​

When generating your JSON schema, you can:

  • Use AI schema generation: Select Suggest schema from the node parameters to infer and generate the output schema automatically, based from the prompt contents. You can edit the generated schema afterward; ensure it describes only the payload.

  • Manually write a JSON schema using the definition rules and schema patterns below.

Schema scope​

The output schema describes only the value your node returns from its code or configuration—the actual payload that other nodes use. It does not describe run metadata or the runtime envelope (e.g. results, message, context) shown in execution logs or the Test results tab. Define the schema for the JSON value you would get if you took the node's functional output alone as a standalone JSON document; do not model the wrapper around it.

Definition rules​

When defining an output schema:

  • Match the top-level type exactly: object, array, string, number, boolean, or null.
  • Define the shape recursively:
    • If it's an object, define properties (and optionally required).
    • If it's an array, define items (the schema for each element).
  • Do not reference CloudFlow's reserved fields (e.g., results, message, context). Those are part of the runtime envelope, not the node's functional output.
  • Omit $schema and $id keywords from the output schema. These JSON Schema identifiers are not supported.

Marking sensitive fields​

You can mark specific fields in your schema as sensitive so CloudFlow treats their values as secrets. When a property is marked with "sensitive": true, CloudFlow encrypts the field's value at rest and masks it in the CloudFlow UI and logs where appropriate, while still making the value available to downstream nodes at runtime.

For example, to mark a nested key field as sensitive:

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

Use "sensitive": true only for fields that contain secrets or other confidential values (for example, API keys, tokens, or credentials) so CloudFlow can protect them appropriately.

Schema patterns​

Use these patterns for other payload shapes. Remember: the schema describes only the payload (e.g. the content of results[0]), not the execution wrapper.

Node returns an object:

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

Node returns an array:

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

Node returns a nested object:

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

Node returns an object with required fields:

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

Examples​

Example: Code node returning EC2 instance data​

When a Code node returns data (for example, instance ID and state), the execution output includes CloudFlow's wrapper. You define the output schema for the payload only—the value inside results[0].

Execution output (simplified; the wrapper includes results, message, and context):

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

The payload—the value downstream nodes reference—is the object inside results[0]:

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

Output schema to define (describe only the payload, not the wrapper):

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

Test your schema​

To test your schema, run the node or use saved test data so the output is available. Confirm that the schema matches the payload and that downstream nodes can reference the fields you need. See Test nodes for how to run a node, save test data, and test downstream nodes.

See also​

Last updated on