Document JSON configOverrides

modules/concepts/pages/overrides.adoc

@@ -51,13 +51,78 @@ spec:
 <4> `configOverride` on role group level, takes precedence over overrides at role level.
 
 The roles, as well as the configuration file and configuration settings available depend on the specific product.
-All override property values must be strings.
 The properties will be formatted and escaped correctly into the file format used by the product, which is again product specific.
-This can be a `.properities` file, XML, YAML or JSON.
+This can be a `.properties` file, XML, or YAML.
 
 You can also set the property to an empty string (`my.property: ""`), which effectively disables the property the operator would write out normally.
 In case of a `.properties` file, this will show up as `my.property=` in the `.properties` file.
 
+[#json-config-overrides]
+=== JSON config overrides
+
+Some products accept JSON config files (e.g. Open Policy Agent's `config.json`).
+The above mentioned `Map<String, String>` structure doesn't fit this, so there is a special mechanism for these files.
+
+==== JSON Merge Patch (https://datatracker.ietf.org/doc/html/rfc7396[RFC 7396])
+
+The `jsonMergePatch` is used best in case you want to make simple additions or changes to the config.
+
+[source,yaml]
+----
+configOverrides:
+  config.json:
+    jsonMergePatch:
+      bundles:
+        authz:
+          polling:
+            min_delay_seconds: 3
+----
+
+==== JSON Patch (https://datatracker.ietf.org/doc/html/rfc6902[RFC 6902])
+
+The `jsonPatch` is more complicated than the `jsonMergePatch`, but offers more flexibility, e.g. to remove config items.
+
+[source,yaml]
+----
+configOverrides:
+  config.json:
+    jsonPatches:
+      - '{"op": "test", "path": "/0/name", "value": "Andrew"}'
+      - '{"op": "add", "path": "/0/happy", "value": true}'
+      - '{"op": "remove", "path": "/0/birthDate"}'
+----
+
+==== User provided JSON
+
+As an escape hatch you can also provide your custom JSON config, which the operator will pass to the product.
+
+[source,yaml]
+----
+configOverrides:
+  config.json:
+    userProvided: {
+      "myString": "test",
+      "myList": ["test"],
+      "myBool": true,
+      "my": {"nested.field.with.dots": 42}
+    }
+----
+
+NOTE: JSON is a valid subset of YAML, so you can inline JSON into YAML.
+However, you can also use YAML syntax:
+
+[source,yaml]
+----
+configOverrides:
+  config.json:
+    userProvided:
+      myString: test
+      myList: [test]
+      myBool: true
+      my:
+        nested.field.with.dots: 42
+----
+
 [#env-overrides]
 == Environment variable overrides