JSON JQ Transform

The JSON JQ Transform task allows the processing of JSON data using jq.

A JSON JQ Transform task evaluates a queryExpression using jq syntax to transform JSON data provided as input parameters. The task processes the data based on the specified query, and the output is a transformed JSON object or array.

Task parameters

Configure these parameters for the JSON JQ Transform task.

Parameter	Description	Required/ Optional
inputParameters	JSON object containing the configuration data for task execution. Supports string, number, boolean, null, and object/array.	Required.
inputParameters.queryExpression	A string representing a JQ (JSON Query) expression. This expression is used to transform the JSON data.	Required.

Note

If your JSON JQ Transform expression references a workflow secret (such as ${workflow.secrets.<secret-name>}), the resolved value is automatically masked in the task output. For details on masking behavior, see Masking Parameters.

The following are generic configuration parameters that can be applied to the task and are not specific to the JSON JQ Transform task.

Schema parameters

You can enforce input/output validation for the task using the following parameters. Refer to Schema Validation for a full guide.

Parameter	Description	Required/ Optional
taskDefinition.enforceSchema	Whether to enforce schema validation for task inputs/outputs. Set to true to enable validation.	Optional.
taskDefinition.inputSchema	The name and type of the input schema to be associated with the task.	Required if enforceSchema is set to true.
taskDefinition.outputSchema	The name and type of the output schema to be associated with the task.	Required if enforceSchema is set to true.

Other generic parameters

Here are other parameters for configuring the task behavior.

Parameter	Description	Required/ Optional
optional	Whether the task is optional. If set to`true`, any task failure is ignored, and the workflow continues with the task status updated to `COMPLETED_WITH_ERRORS`. However, the task must reach a terminal state. If the task remains incomplete, the workflow waits until it reaches a terminal state before proceeding.	Optional.

Task configuration

This is the task configuration for a JSON JQ Transform task.

{
  "name": "json_transform",
  "taskReferenceName": "json_transform_ref",
  "type": "JSON_JQ_TRANSFORM",
  "inputParameters": {
    "persons": [
      {
        "name": "some",
        "last": "name",
        "email": "mail@mail.com",
        "id": 1
      },
      {
        "name": "some2",
        "last": "name2",
        "email": "mail2@mail.com",
        "id": 2
      }
    ],
    "queryExpression": ".persons | map({user:{email,id}})"
  }
}

Task output

The JSON JQ Transform task will return the following parameters.

Parameter	Description
resultList	List of results returned by the JQ expression.
result	The first element of the resultList.
error	Optional error message if the JQ query fails.

Adding a JSON JQ Transform task in UI

To add a JSON JQ Transform task:

In your workflow, select the (+) icon and add a JSON JQ Transform task.
In Script Parameters, add the parameter that the JQ expression will evaluate.
In JQ expression, enter the expression to be evaluated.

Adding JQ Transform task

Examples

Here are some examples for using the JSON JQ Transform task.

Using JSON JQ Transform task in a workflow

This example builds a workflow that uses a JSON JQ Transform task to concatenate two arrays by using a JQ expression.

To create a workflow:

Go to Definitions > Workflow, from the left navigation menu on your Conductor cluster.
Select + Define workflow.
In the Code tab, paste the following workflow definition:

{
 "name": "jq_transform_concat_arrays",
 "description": "Concatenates two arrays using a JSON JQ Transform task.",
 "version": 1,
 "tasks": [
   {
     "name": "jq_example_task",
     "taskReferenceName": "jq_example_ref",
     "inputParameters": {
       "key1": {
         "value1": "${workflow.input.value1}"
       },
       "key2": {
         "value2": "${workflow.input.value2}"
       },
       "queryExpression": "{ key3: (.key1.value1 + .key2.value2) }"
     },
     "type": "JSON_JQ_TRANSFORM"
   }
 ],
 "inputParameters": [
   "value1",
   "value2"
 ],
 "outputParameters": {
   "key3": "${jq_example_ref.output.result.key3}"
 },
 "schemaVersion": 2
}

Select Save > Confirm.

To run the workflow:

Go to the Run tab, and enter the Input params. For example:

{
  "value1": ["a", "b"],
  "value2": ["c", "d"]
}

Select Execute.

This takes you to the workflow execution page. Once completed, it returns the workflow output as follows:

Workflow output

How the JSON JQ Transform task works in this workflow

The input parameters for the JSON JQ Transform task are defined as follows:

"inputParameters": {
       "key1": {
         "value1": "${workflow.input.value1}"
       },
       "key2": {
         "value2": "${workflow.input.value2}"
       }
     }

The task uses these inputs:

key1.value1: First array (["a", "b"])
key2.value2: Second array (["c", "d"])

The queryExpression parameter contains the following JQ expression:

{ key3: (.key1.value1 + .key2.value2) }

This expression concatenates the arrays value1 and value2 into a single array under key3.

In the workflow execution, select the task jq_example_task to view the task output. The task returns:

result—The first result produced by the JQ expression.
resultList—All results produced by the expression. In this example, the expression returns a single result.

Workflow output

Clean up an API response using JSON JQ Transform

This example builds a workflow that retrieves recent stories from the Hacker News Algolia API and uses a JSON JQ Transform task to filter and reshape the API response.

To create a workflow:

Go to Definitions > Workflow, from the left navigation menu on your Conductor cluster.
Select + Define workflow.
In the Code tab, paste the following workflow definition:

{
 "name": "jq_cleanup_hn_items",
 "description": "Retrieves recent Hacker News items and filters/reshapes the response using JSON JQ Transform.",
 "version": 1,
 "tasks": [
   {
     "name": "get_hn_items",
     "taskReferenceName": "hn_items_ref",
     "inputParameters": {
       "uri": "https://hn.algolia.com/api/v1/search_by_date?tags=story&query=${workflow.input.query}",
       "method": "GET",
       "accept": "application/json",
       "contentType": "application/json"
     },
     "type": "HTTP"
   },
   {
     "name": "jq_cleanup_items",
     "taskReferenceName": "jq_cleanup_items_ref",
     "inputParameters": {
       "items": "${hn_items_ref.output.response.body.hits}",
       "queryExpression": "[.items[] | select(.created_at > \"${workflow.input.cutoff_date}\") | { occurred_at: .created_at, member: { hn: .author }, title: .title }]"
     },
     "type": "JSON_JQ_TRANSFORM"
   }
 ],
 "inputParameters": [
   "query",
   "cutoff_date"
 ],
 "outputParameters": {
   "cleaned_items": "${jq_cleanup_items_ref.output.result}"
 },
 "schemaVersion": 2
}

Select Save > Confirm.

To run the workflow:

Go to the Run tab, and enter the Input params. For example:

{
  "query": "distributed systems",
  "cutoff_date": "2025-09-30T00:00:00Z"
}

Select Execute.

This takes you to the workflow execution page. Once completed, it returns the following output:

Workflow output

How the JSON JQ Transform task works in this workflow

The HTTP task via the Hacker News API returns a verbose JSON response that includes an array. Each entry contains many fields, such as timestamps, author details, URLs, and metadata.

HTTP task output

In this workflow, the JSON JQ Transform task reduces that response to a simplified structure that includes only:

When the story was created (occurred_at)
Who created it (member.hn)
The story title (title)

The JSON JQ Transform task applies this JQ expression:

[.items[] | select(.created_at > "${workflow.input.cutoff_date}") | { occurred_at: .created_at, member: { hn: .author }, title: .title }]

This expression:

Iterates over each entry in the .items array.
Filters entries where created_at is later than the specified cutoff date.
Constructs a simplified object that includes only the required fields.
Returns the results as an array.

The JSON JQ Transform task returns:

result: The transformed array returned by the JQ expression.
resultList: All results produced by the expression. In this example, the expression returns a single array.

Workflow output

Task parameters​

Task configuration​

Task output​

Adding a JSON JQ Transform task in UI​

Examples​

Task parameters

Task configuration

Task output

Adding a JSON JQ Transform task in UI

Examples