Skip to content
|
search
Plugin Hub
header icon

jq

You are browsing documentation for an outdated plugin version. See the latest documentation here.

The jq plugin enables arbitrary jq transformations on JSON objects included in API requests or responses.

The configuration accepts two sets of options: one for the request and another for the response. For both the request and response, a jq program string can be included, along with some jq option flags and a list of media types.

One of the configured media types must be included in the Content-Type header of the request or response for the jq program to run. The default media type in the Content-Type header is application/json.

In the response context, you can also specify a list of status codes, one of which must match the response status code. The default response status code is 200.

Notes:

  • In the response context the entire body must be buffered to be processed. This requirement also implies that the Content-Length header will be dropped if present, and the body transferred with chunked encoding.
  • To use this plugin in Konnect, upgrade your runtimes to at least v2.6.0.0.

See jq’s documentation on Basic filters for more information on writing programs with jq.

Configuration Reference

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

Form Parameter Description
name

required

Type: string

 The name of the plugin, in this case jq.
service.name or service.id

optional

Type: string

The name or ID of the service the plugin targets.

Set one of these parameters if adding the plugin to a service through the top-level /plugins endpoint.

Not required if using /services/SERVICE_NAME|SERVICE_ID/plugins.
route.name or route.id

optional

Type: string

The name or ID of the route the plugin targets.

Set one of these parameters if adding the plugin to a route through the top-level /plugins endpoint.

Not required if using /routes/ROUTE_NAME|ROUTE_ID/plugins.
consumer.name or consumer.id

optional


Type: string

The name or ID of the consumer the plugin targets.

Set one of these parameters if adding the plugin to a consumer through the top-level /plugins endpoint.

Not required if using /consumers/CONSUMER_NAME|CONSUMER_ID/plugins.
enabled

optional

Type: boolean

Default value: true

 Whether this plugin will be applied.
config.request_jq_program

semi-optional

Type: string


The jq program to run on the request body. For example, .[0] | { "X-Foo": .foo }. Either request_jq_program or response_jq_plugin must be included in the configuration.
config.request_jq_program_options

optional

Type: record


Boolean option flags to modify the run behavior of the jq program run on the request body.

  • compact_output: Returns output in a compact form without additional spacing, and with each JSON object on a single line. Defaults to true. Set to false for “pretty” output.
  • raw_output: Outputs as raw strings, not JSON quoted. Default is false.
  • join_output: Similar to raw_output but does not output newline separators. Default is false.
  • ascii_output: jq usually outputs non-ASCII Unicode codepoints as UTF-8, even if the input specified them as escape sequences (like \u03bc). Using this option, you can force jq to produce pure ASCII output, replacing every non-ASCII character with the equivalent escape sequence. Default is false.
  • sort_keys: Outputs the fields of each object with the keys in sorted order. Default is false.
config.request_if_media_type

optional

Type: array of strings

Default value: [“application/json”]


A list of media type strings. The media type included in the Content-Type request header must match one of the media types on this list for the program to run.
config.response_jq_program

semi-optional

Type: string


The jq program to run on the response body. For example, .[0] | { "X-Foo": .foo }. Either request_jq_program or response_jq_plugin must be included in configuration.
config.response_jq_program_options

optional

Type: record


Boolean option flags to modify the run behavior of the jq program run on the response body.

  • compact_output: Returns output in a compact form without additional spacing, and with each JSON object on a single line. Defaults to true. Set to false for “pretty” output.
  • raw_output: Outputs as raw strings, not JSON quoted. Default is false.
  • join_output: Similar to raw_output but does not output newline separators. Default is false.
  • ascii_output: jq usually outputs non-ASCII Unicode codepoints as UTF-8, even if the input specified them as escape sequences (like \u03bc). Using this option, you can force jq to produce pure ASCII output, replacing every non-ASCII character with the equivalent escape sequence. Default is false.
  • sort_keys: Outputs the fields of each object with the keys in sorted order. Default is false.
config.response_if_media_type

optional

Type: array of strings

Default value: [“application/json”]


A list of media type strings. The media type included in the Content-Type response header must match one of the media types on this list for the program to run.
config.response_if_status_code

optional

Type: array of integers

Default value: [200]


A list of HTTP response status codes. The response status code must match one of the response status codes on this list for the program to run.