JSON

source	condition	target
✔	✔	✔

source

condition

target

✔

Description

The json resource reads and writes a single value in a JSON document, addressed by a Dasel selector.

source: Reads one value out of one file and returns it. Only a single file is accepted (files with more than one entry fails with source only supports one file).
condition: Reads the same value and compares it to value, or to the source output when value is unset. With files, every file must match for the condition to pass.
target: Writes value (or the source output) at the given key. Files already holding that value are reported as up to date and left untouched, so a target that changes nothing does not create a commit.

Parameters

Name	Type	Description
engine	string	“engine” defines the engine used to manipulate the json file. compatible: source condition target default: dasel/v1 remark: accepted values are “dasel/v1”, “dasel/v2”, “dasel/v3” and “dasel”. “dasel” selects the latest dasel engine, currently “dasel/v3”. “dasel/v1” and “dasel/v2” are deprecated in favor of “dasel/v3”. example: engine: dasel/v3
file	string	“file” defines the path of the json file to use. compatible: source condition target remark: “file” and “files” are mutually exclusive. the schemes “https://”, “http://” and “file://” are supported in a source or a condition. example: file: package.json file: https://nodejs.org/dist/index.json
files	array	“files” defines the list of json file paths to use. compatible: condition target remark: “file” and “files” are mutually exclusive. the schemes “https://”, “http://” and “file://” are supported in a condition.
key	string	“key” defines the json key path to use. compatible: source condition target remark: “key” or “query” is required. “key” accepts a dasel query matching the selected engine, more information on https://github.com/tomwright/dasel example: key: $.name key: name file: https://nodejs.org/dist/index.json key: .(lts!=false).version
query	string	“query” defines an advanced dasel v1 query returning several values. compatible: source condition target remark: “query” is only used by the “dasel/v1” engine. The engines “dasel/v2” and “dasel/v3” require “key” instead. in a source, “query” and “versionfilter” must be used together. “query” accepts a dasel query, more information on https://github.com/tomwright/dasel example: query: .name query: “.[*].tag_name”
value	string	“value” defines the value associated with the json key. compatible: condition target default: the output of the associated source.
versionfilter	object	“versionfilter” defines the version pattern and its kind, such as “regex”, “semver” or “latest”. compatible: source remark: with the “dasel/v1” engine, “versionfilter” and “query” must be used together. more information on https://www.updatecli.io/docs/core/versionfilter/
kind	string	“kind” defines the versioning scheme used to select a version. default: latest remark: accepted values are “latest”, “semver”, “regex”, “regex/semver”, “time”, “regex/time”, “lex” and “pep440”. “latest” returns the last version of the list. “lex” sorts the versions lexicographically and returns the last one. “pep440” follows https://peps.python.org/pep-0440/ example: kind: semver
pattern	string	“pattern” defines the version pattern, according to “kind”. default: latest: “latest” semver and pep440: “” regex: “.” time and regex/time: “2006-01-02” remark: for “latest”, “latest” returns the last version, any other value must match a version exactly. for “semver” and “regex/semver”, it is a semantic versioning constraint. for “pep440”, it is a pep440 version specifier. for “regex”, it is a regular expression. for “time” and “regex/time”, it is a Go date layout. ignored by “lex”. example: pattern: ~1.2 pattern: “>=1.0.0 <2.0.0” pattern: ^v\d+.\d+.\d+$
regex	string	“regex” defines the regular expression extracting the version from each entry. remark: only used by the kinds “regex/semver” and “regex/time”. the value of the first capture group is used as the version. example: regex: ^v(\d+.\d+.\d+)$
replaceall	object	“replaceall” applies a regular expression replacement to each version before filtering. remark: only used by the kinds “regex”, “regex/semver” and “regex/time”. the replacement runs before “pattern” or “regex” is evaluated. example: `replaceall: pattern: "_" replacement: "."` turns “curl-8_15_0” into “curl-8.15.0”.
strict	boolean	“strict” enforces strict semantic versioning rules when parsing versions. default: false remark: only used by the kinds “semver” and “regex/semver”.

file or files is mandatory, as is key or query; missing either aborts the run with wrong spec content. The two are mutually exclusive (setting both fails with parameter "file" and "files" are mutually exclusive).

value: Defaults to the source output. Setting it explicitly makes the condition or target independent of any source.
versionfilter: Only meaningful for a source, and only when the selector returns several values - it picks one out of the list. See the "Version Filtering" page.

Note	`multiple` is deprecated and hidden from the table above. It still works, logging a warning, and a `key` used together with it is silently rewritten into `query`. Use a selector that returns several values instead.

Engines

engine selects which version of Dasel parses the file. It matters more than it looks: the selector syntax is not portable between versions.

Value Behaviour

Value	Behaviour
`dasel/v1`	Default when `engine` is unset. Deprecated - every run logs a warning.
`dasel/v2`	Deprecated - every run logs a warning.
`dasel/v3`	Current engine.
`dasel`	Alias resolving to the latest engine, currently `dasel/v3`.

dasel/v1

Default when engine is unset. Deprecated - every run logs a warning.

dasel/v2

Deprecated - every run logs a warning.

dasel/v3

Current engine.

dasel

Alias resolving to the latest engine, currently dasel/v3.

The leading dot is the trap when migrating:

Selector dasel/v1 dasel/v2 dasel/v3

Selector	`dasel/v1`	`dasel/v2`	`dasel/v3`
`.version`	✔	✔	✗ parse error
`version`	✔	✔	✔

.version

✔

✗ parse error

version

✔

On dasel/v3 a leading dot fails with error parsing selector: failed to parse: unexpected token 29 "." at position 0. Multi-value selectors differ too (.deps.[*].version on dasel/v1 is written .deps.all().version on dasel/v2).

Warning

query is a dasel/v1 parameter. On dasel/v2 and dasel/v3 a query without a key is a validation error:

engine "dasel/v3" requires the parameter "key" over "query"

On dasel/v1 the split is the other way round: query is the multi-value form and pairs with versionfilter, while key returns exactly one value. Using query without versionfilter, or versionfilter without query, fails a source with in the context of a source, parameter "versionfilter" and "query" must be used together. That rule does not apply to dasel/v2 and dasel/v3, where key covers both cases.

Remote files

file accepts https://, http:// and file:// schemes for a source and a condition, which is how the example below reads the Node.js release index straight from nodejs.org.

A target cannot write to a URL, and refuses rather than silently skipping:

URL scheme is not supported for Json target: "https://nodejs.org/dist/index.json"

Examples

Retrieves a value from a JSON file

# updatecli.yaml
name: Basic Json Example

scms:
  default:
    kind: git
    spec:
      url: https://github.com/updatecli/updatecli.git

sources:
  local:
    name: Get value from json
    kind: json
    scmid: default
    spec:
      file: pkg/plugins/resources/json/testdata/data.json
      key: firstName
  http:
    name: Get value from json
    kind: json
    spec:
      file: https://www.updatecli.io/schema/latest/config.json
      key: $id

conditions:
  local:
    name: Test value from json
    kind: json
    sourceid: local
    scmid: default
    spec:
      file: pkg/plugins/resources/json/testdata/data.json
      key: firstName
  http:
    name: Test value from json
    kind: json
    disablesourceinput: true
    spec:
      file: https://www.updatecli.io/schema/latest/config.json
      key: $schema
      value: http://json-schema.org/draft-04/schema

targets:
  local:
    name: Test value from json
    kind: json
    sourceid: local
    scmid: default
    spec:
      file: pkg/plugins/resources/json/testdata/data.json
      key: firstName
      value: John

Uses a path to find a value in a JSON file

# jenkins-old-versions.yaml
# We're working with https://updates.jenkins.io/tiers.json
# {"stableCores":["2.346.3","2.361.1", ...,"2.414.2"],"weeklyCores":["2.364","2.371",...,"2.425"]}
# This example finds the oldest weekly and stable supported Jenkins versions (first in the list)
# It also finds the latest weekly and stable Jenkins versions (last in the list)
name: Find oldest supported Jenkins versions

scms:
  default:
    kind: github
    spec:
      user: "{{ .github.user }}"
      email: "{{ .github.email }}"
      owner: "{{ .github.owner }}"
      repository: "{{ .github.repository }}"
      token: "{{ requiredEnv .github.token }}"
      username: "{{ .github.username }}"
      branch: "{{ .github.branch }}"

sources:
  JenkinsOldestSupportedWeekly:
    name: Get the oldest supported Jenkins weekly version
    kind: json
    scmid: default
    spec:
      file: https://updates.jenkins.io/tiers.json
      key: "weeklyCores.[0]"
  JenkinsOldestSupportedStable:
    name: Get the oldest supported Jenkins stable version
    kind: json
    scmid: default
    spec:
      file: https://updates.jenkins.io/tiers.json
      # `key` targets only one value, the first one of the list in this case
      key: "stableCores.[0]"
  JenkinsNewestWeeklyVersion:
    name: Get the newest supported Jenkins weekly version
    kind: json
    spec:
      file: https://updates.jenkins.io/tiers.json
      # Here we use `query` to target all the values in the list
      query: "weeklyCores.[*]"
      # We use `versionfilter` to filter the list of versions
      # Combined with `semver`, we can target the latest version that follows the semver pattern
      versionfilter:
        kind: semver
  JenkinsNewestStableVersion:
    name: Get the newest supported Jenkins stable version
    kind: json
    spec:
      file: https://updates.jenkins.io/tiers.json
      query: "stableCores.[*]"
      versionfilter:
        kind: semver

conditions:
  # Test that the oldest Jenkins supported weekly version exists
  jenkinsOldestSupportedWeeklyVersion:
    kind: jenkins
    spec:
      release: weekly
    sourceid: JenkinsOldestSupportedWeekly
  # Test that the oldest Jenkins supported stable version exists
  jenkinsOldestSupportedStableVersion:
    kind: jenkins
    sourceid: JenkinsOldestSupportedStable
  # Test that the newest Jenkins supported weekly version exists
  jenkinsNewestSupportedWeeklyVersion:
    kind: jenkins
    spec:
      release: weekly
    sourceid: JenkinsNewestWeeklyVersion
  # Test that the newest Jenkins supported stable version exists
  jenkinsNewestSupportedStableVersion:
    kind: jenkins
    sourceid: JenkinsNewestStableVersion
targets:
  setJenkinsOldestSupportedWeekly:
    kind: file
    name: "Bump Jenkins oldest weekly supported version in the \"Choosing a version\" page"
    sourceid: JenkinsOldestSupportedWeekly
    spec:
      file: content/doc/developer/plugin-development/choosing-jenkins-baseline.adoc
      matchpattern: >-
        (.*Do not use versions no longer supported by the update center.*older than )(.*)( for weekly releases.*for LTS releases.*)
      replacepattern: >-
        ${1}{{ source "JenkinsOldestSupportedWeekly" }}${3}
    scmid: default
  setJenkinsOldestSupportedStable:
    kind: file
    name: "Bump Jenkins oldest stable supported version in the \"Choosing a version\" page"
    sourceid: JenkinsOldestSupportedStable
    spec:
      file: content/doc/developer/plugin-development/choosing-jenkins-baseline.adoc
      matchpattern: >-
        (.*Do not use versions no longer supported by the update center.* weekly releases, and )(.*)( for LTS releases.*)
      replacepattern: >-
        ${1}{{ source "JenkinsOldestSupportedStable" }}${3}
    scmid: default

actions:
  default:
    kind: github/pullrequest
    scmid: default
    title: Bump Jenkins LTS and weekly versions in various parts of the documentation
    spec:
      labels:
        - dependencies
        - chore

Links

Last updated on August 2, 2026

Jenkins

Maven Repository

Docs

Updatecli

Title here

JSON

Description

Parameters

Engines

Remote files

Examples

Retrieves a value from a JSON file

Uses a path to find a value in a JSON file

Links

JSON

Description#

Parameters#

Engines#

Remote files#

Examples#

Retrieves a value from a JSON file#

Uses a path to find a value in a JSON file#

Links#

Description

Parameters

Engines

Remote files

Examples

Retrieves a value from a JSON file

Uses a path to find a value in a JSON file

Links