jq

Wrapper rule around the popular jq utility.

For jq documentation, see https://stedolan.github.io/jq/.

Usage examples

load("@aspect_bazel_lib//lib:jq.bzl", "jq")

Create a new file bazel-out/.../no_srcs.json containing some JSON data:

jq(
    name = "no_srcs",
    srcs = [],
    filter = ".name = "Alice"",
)

Remove a field from package.json:

The output path bazel-out/.../package.json matches the path of the source file, which means you must refer to the label :no_dev_deps to reference the output, since Bazel doesn't provide a label for an output file that collides with an input file.

jq(
    name = "no_dev_deps",
    srcs = ["package.json"],
    out = "package.json",
    filter = "del(.devDependencies)",
)

Merge data from bar.json on top of foo.json, producing foobar.json:

jq(
    name = "merged",
    srcs = ["foo.json", "bar.json"],
    filter = ".[0] * .[1]",
    args = ["--slurp"],
    out = "foobar.json",
)

Long filters can be split over several lines with comments:

jq(
    name = "complex",
    srcs = ["a.json", "b.json"],
    filter = """
        .[0] as $a
        # Take select fields from b.json
        | (.[1] | {foo, bar, tags}) as $b
        # Merge b onto a
        | ($a * $b)
        # Combine 'tags' array from both
        | .tags = ($a.tags + $b.tags)
        # Add new field
        + {\"aspect_is_cool\": true}
    """,
    args = ["--slurp"],
)

Load filter from a file filter.jq, making it easier to edit complex filters:

jq(
    name = "merged",
    srcs = ["foo.json", "bar.json"],
    filter_file = "filter.jq",
    args = ["--slurp"],
    out = "foobar.json",
)

Convert genquery output to JSON.

genquery(
    name = "deps",
    expression = "deps(//some:target)",
    scope = ["//some:target"],
)

jq(
    name = "deps_json",
    srcs = [":deps"],
    args = [
        "--raw-input",
        "--slurp",
    ],
    filter = "{ deps: split("\n") | map(select(. | length > 0)) }",
)

When Bazel is run with --stamp, replace some properties with version control info:

jq(
    name = "stamped",
    srcs = ["package.json"],
    filter = "|".join([
        # Don't directly reference $STAMP as it's only set when stamping
        # This 'as' syntax results in $stamp being null in unstamped builds.
        "$ARGS.named.STAMP as $stamp",
        # Provide a default using the "alternative operator" in case $stamp is null.
        ".version = ($stamp[0].BUILD_EMBED_LABEL // "<unstamped>")",
    ]),
)

jq is exposed as a "Make variable", so you could use it directly from a genrule by referencing the toolchain.

genrule(
    name = "case_genrule",
    srcs = ["a.json"],
    outs = ["genrule_output.json"],
    cmd = "$(JQ_BIN) '.' $(location a.json) > $@",
    toolchains = ["@jq_toolchains//:resolved_toolchain"],
)

Macros and Functions

jq

Invoke jq with a filter on a set of json input files.

Example usage (generated):

load("@aspect_bazel_lib//lib:jq.bzl", "jq")

jq(
    # Name of the rule
    name = "",
    # List of input files
    srcs = [],
)

name

Required.

Name of the rule

srcs

Required.

List of input files. May be empty.

filter

Optional. Default: None

Filter expression (https://stedolan.github.io/jq/manual/#Basicfilters). Subject to stamp variable replacements, see Stamping. When stamping is enabled, a variable named "STAMP" will be available in the filter.

Be careful to write the filter so that it handles unstamped builds, as in the example above.

filter_file

Optional. Default: None

File containing filter expression (alternative to filter)

args

Optional. Default: []

Additional args to pass to jq

out

Optional. Default: None

Name of the output json file; defaults to the rule name plus ".json"

data

Optional. Default: []

List of additional files. May be empty.

expand_args

Optional. Default: False

Run bazel's location and make variable expansion on the args.

kwargs

Optional.

Other common named parameters such as tags or visibility