Jenkins Pipeline JSON Configuration Techniques

If you need to read JSON in a Jenkins Pipeline, the usual answer is readJSON. It is the Jenkins pipeline step designed for this job, and it handles the two cases most teams actually have: loading a JSON file from the workspace and parsing a JSON string from a parameter, API response, or shell command.

The important distinction is that you do not write the Jenkinsfile itself in JSON. You keep the pipeline in Groovy, then parse JSON as configuration or runtime data. When the readJSON step is not available, Groovy's JsonSlurper is the clean fallback.

Quick Answer: readJSON, JsonSlurper, or jq?

• Use readJSON file: when the JSON lives in your repo or is created in the build workspace.
• Use readJSON text: when JSON comes from a Jenkins parameter, an API response, or command output.
• Add returnPojo: true when you want plain Groovy-friendly LinkedHashMap and ArrayList objects instead of json-lib objects.
• Use JsonSlurper when the Pipeline Utility Steps plugin is not installed or you want a plugin-free fallback.
• Use jq or Python on the agent only for heavy filtering, reshaping, or very large JSON payloads where shell tools are a better fit than Groovy.

Use readJSON First for Most Jenkins Pipelines

The readJSON step comes from the Pipeline Utility Steps plugin, not Jenkins core. Current Jenkins documentation shows that it accepts either file or text input, and returnPojo: true converts the result into plain Java collections. That is usually the easiest form to work with inside Declarative script blocks, Scripted Pipeline, and shared library code.

For repo-backed configuration, the path is relative to the workspace. That means you normally need to check out the repository before trying to read the JSON file.

pipeline {
    agent any

    stages {
        stage('Load config') {
            steps {
                checkout scm

                script {
                    def cfg = readJSON file: 'ci/config.json', returnPojo: true

                    if (!cfg.deploy?.environment) {
                        error('ci/config.json is missing deploy.environment')
                    }

                    echo "Deploy environment: ${cfg.deploy.environment}"
                    echo "Services: ${cfg.services.join(', ')}"
                }
            }
        }
    }
}

This pattern is usually better than hardcoding values in the Jenkinsfile because the JSON can be reviewed, versioned, and validated outside Jenkins. It also matches common search intent such as "read json jenkins" and "jenkins pipeline read json": read a file, turn it into a map, and fail fast if a required key is missing.

Parse JSON Parameters and API Payloads with readJSON text

When JSON is not stored as a file, use readJSON text:. A Jenkins text parameter is a better fit than a single-line string parameter because it is easier to paste, review, and edit valid JSON in the job UI.

The same technique works for API responses. If another step gives you a JSON string, parse it with readJSON text: responseBody, returnPojo: true and then access fields exactly as you would from a file-backed config object.

pipeline {
    agent any

    parameters {
        text(
            name: 'OVERRIDES_JSON',
            defaultValue: '{\n  "deploy": { "environment": "staging" },\n  "dryRun": true\n}',
            description: 'Optional JSON overrides'
        )
    }

    stages {
        stage('Apply overrides') {
            steps {
                script {
                    def overrides = readJSON text: params.OVERRIDES_JSON, returnPojo: true

                    echo "Dry run: ${overrides.dryRun}"
                    echo "Environment: ${overrides.deploy.environment}"
                }
            }
        }
    }
}

Fallback: readFile Plus JsonSlurper

If you see No such DSL method 'readJSON', your controller probably does not have the Pipeline Utility Steps plugin available to that job. In that case, the simplest fallback is to read the file as text and parse it with Groovy's built-in JsonSlurper.

pipeline {
    agent any

    stages {
        stage('Load config without readJSON') {
            steps {
                checkout scm

                script {
                    def raw = readFile('ci/config.json')
                    def cfg = new groovy.json.JsonSlurper().parseText(raw) as Map

                    echo "Deploy environment: ${cfg.deploy.environment}"
                }
            }
        }
    }
}

This fallback is also useful in shared library helpers when you want to stay close to standard Groovy. The tradeoff is that you lose the convenience of the dedicated Jenkins step and need to manage file reading yourself.

Common Problems and Fixes

• readJSON is not recognized: Install or update the Pipeline Utility Steps plugin. The step is not part of Jenkins core.
• The file cannot be found: The file argument is resolved relative to the workspace, so make sure the repository has been checked out and the path matches the workspace layout.
• JSON pasted into parameters fails to parse: Use a text parameter, avoid trailing commas, and validate the JSON before saving the job or triggering the build.
• Keys are missing at runtime: Validate required fields explicitly and call error() with a clear message instead of letting a null value fail later in deployment logic.
• The payload is large or heavily nested: Offload expensive filtering to jq or a small Python script on the agent instead of writing large Groovy transformations in the Jenkinsfile.

Practical Guidance

• Do not store secrets in JSON files committed to Git. Keep tokens, passwords, and API keys in Jenkins Credentials and merge them into runtime configuration only when the pipeline runs.
• Prefer returnPojo: true when using readJSON. Plain maps and lists are easier to inspect, pass around, and test in pipeline code.
• Keep the Jenkinsfile thin. Put stable configuration in JSON, validate it early, then extract only the few values the stage actually needs.
• Log carefully. Pretty-printing JSON is helpful for debugging, but only for non-sensitive fields that are safe to expose in build logs.

Conclusion

For most teams, the best current answer to "how do I read JSON in Jenkins?" is still readJSON file: for workspace files and readJSON text: for parameters or API responses, usually with returnPojo: true. If that step is unavailable, readFile plus JsonSlurper gives you a reliable fallback without changing the overall pipeline design.