community.general.json_patch filter – Apply a JSON-Patch (RFC 6902) operation to an object

Note

This filter plugin is part of the community.general collection (version 10.7.5).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general. You need further requirements to be able to use this filter plugin, see Requirements for details.

To use it in a playbook, specify: community.general.json_patch.

New in community.general 10.3.0

Synopsis

  • This filter applies a single JSON patch operation and returns a modified object.

  • If the operation is a test, the filter returns an ummodified object if the test succeeded and a none value otherwise.

Requirements

The below requirements are needed on the local controller node that executes this filter.

  • jsonpatch

Input

This describes the input of the filter, the value before | community.general.json_patch.

Parameter

Comments

Input

any / required

A list or a dictionary representing a JSON object, or a string containing a JSON object.

Positional parameters

This describes positional parameters of the filter. These are the values positional1, positional2 and so on in the following example: input | community.general.json_patch(positional1, positional2, ...)

Parameter

Comments

op

string / required

Operation to perform (see RFC 6902).

Choices:

  • "add"

  • "copy"

  • "move"

  • "remove"

  • "replace"

  • "test"

path

string / required

JSON Pointer path to the target location (see RFC 6901).

value

any

Value to use in the operation. Ignored for op=copy, op=move, and op=remove.

Keyword parameters

This describes keyword parameters of the filter. These are the values key1=value1, key2=value2 and so on in the following example: input | community.general.json_patch(key1=value1, key2=value2, ...)

Parameter

Comments

fail_test

boolean

If false, a failed op=test will return none. If true, the filter invocation will fail with an error.

Choices:

  • false ← (default)

  • true

from

string

The source location for the copy and move operation. Mandatory for op=copy and op=move, ignored otherwise.

Notes

Note

  • When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters: input | community.general.json_patch(positional1, positional2, key1=value1, key2=value2)

See Also

See also

RFC 6902

JavaScript Object Notation (JSON) Patch

RFC 6901

JavaScript Object Notation (JSON) Pointer

jsonpatch Python Package

A Python library for applying JSON patches

Examples

- name: Insert a new element into an array at a specified index
  ansible.builtin.debug:
    msg: "{{ input | community.general.json_patch('add', '/1', {'baz': 'qux'}) }}"
  vars:
    input: ["foo": { "one": 1 }, "bar": { "two": 2 }]
  # => [{"foo": {"one": 1}}, {"baz": "qux"}, {"bar": {"two": 2}}]

- name: Insert a new key into a dictionary
  ansible.builtin.debug:
    msg: "{{ input | community.general.json_patch('add', '/bar/baz', 'qux') }}"
  vars:
    input: { "foo": { "one": 1 }, "bar": { "two": 2 } }
  # => {"foo": {"one": 1}, "bar": {"baz": "qux", "two": 2}}

- name: Input is a string
  ansible.builtin.debug:
    msg: "{{ input | community.general.json_patch('add', '/baz', 3) }}"
  vars:
    input: '{ "foo": { "one": 1 }, "bar": { "two": 2 } }'
  # => {"foo": {"one": 1}, "bar": { "two": 2 }, "baz": 3}

- name: Existing key is replaced
  ansible.builtin.debug:
    msg: "{{ input | community.general.json_patch('add', '/bar', 'qux') }}"
  vars:
    input: { "foo": { "one": 1 }, "bar": { "two": 2 } }
  # => {"foo": {"one": 1}, "bar": "qux"}

- name: Escaping tilde as ~0 and slash as ~1 in the path
  ansible.builtin.debug:
    msg: "{{ input | community.general.json_patch('add', '/~0~1', 'qux') }}"
  vars:
    input: {}
  # => {"~/": "qux"}

- name: Add at the end of the array
  ansible.builtin.debug:
    msg: "{{ input | community.general.json_patch('add', '/-', 4) }}"
  vars:
    input: [1, 2, 3]
  # => [1, 2, 3, 4]

- name: Remove a key
  ansible.builtin.debug:
    msg: "{{ input | community.general.json_patch('remove', '/bar') }}"
  vars:
    input: { "foo": { "one": 1 }, "bar": { "two": 2 } }
  # => {"foo": {"one": 1} }

- name: Replace a value
  ansible.builtin.debug:
    msg: "{{ input | community.general.json_patch('replace', '/bar', 2) }}"
  vars:
    input: { "foo": { "one": 1 }, "bar": { "two": 2 } }
  # => {"foo": {"one": 1}, "bar": 2}

- name: Copy a value
  ansible.builtin.debug:
    msg: "{{ input | community.general.json_patch('copy', '/baz', from='/bar') }}"
  vars:
    input: { "foo": { "one": 1 }, "bar": { "two": 2 } }
  # => {"foo": {"one": 1}, "bar": { "two": 2 }, "baz": { "two": 2 }}

- name: Move a value
  ansible.builtin.debug:
    msg: "{{ input | community.general.json_patch('move', '/baz', from='/bar') }}"
  vars:
    input: { "foo": { "one": 1 }, "bar": { "two": 2 } }
  # => {"foo": {"one": 1}, "baz": { "two": 2 }}

- name: Successful test
  ansible.builtin.debug:
    msg: "{{ input | community.general.json_patch('test', '/bar/two', 2) | ternary('OK', 'Failed') }}"
  vars:
    input: { "foo": { "one": 1 }, "bar": { "two": 2 } }
  # => OK

- name: Unuccessful test
  ansible.builtin.debug:
    msg: "{{ input | community.general.json_patch('test', '/bar/two', 9) | ternary('OK', 'Failed') }}"
  vars:
    input: { "foo": { "one": 1 }, "bar": { "two": 2 } }
  # => Failed

Return Value

Key

Description

Return value

any

A modified object or none if op=test, fail_test=false and the test failed.

Returned: always

Authors

  • Stanislav Meduna (@numo68)