update docs on the extension value replace (#7029)

docs/user-guide/app-extensions.md

@@ -3,7 +3,7 @@ Title: App extensions
 Added: 3.0.0
 ---
 
-# App extensions
+# App Extensions
 
 ADF lets you simplify the app developer's task by providing an **extensible app**
 as a starting point.
@@ -122,6 +122,77 @@ convenient object that implements the [`ExtensionConfig`](../../lib/extensions/s
 Note that the `extension.schema.json` file contains a [JSON schema](http://json-schema.org/)
 that allows for format checking and also text completion in some editors.
 
+### Replacing Values
+
+By default, the data from the extensions gets merged with the existing one.
+
+For example:
+
+**Application Data**
+
+```json
+{
+    "languages": [
+        { "key": "en", "title": "English" },
+        { "key": "it", "title": "Italian" }
+    ]
+}
+```
+
+**Extension Data**
+
+```json
+{
+    "languages": [
+        { "key": "fr", "title": "French" },
+    ]
+}
+```
+
+**Expected Result**
+
+At runtime, the application is going to display three languages
+
+```json
+{
+    "languages": [
+        { "key": "en", "title": "English" },
+        { "key": "it", "title": "Italian" },
+        { "key": "fr", "title": "French" },
+    ]
+}
+```
+
+You can replace the value by using the special key syntax:
+
+```json
+{
+    "<name>.$replace": "<value>"
+}
+```
+
+**Example:**
+
+```json
+{
+    "languages.$replace": [
+        { "key": "fr", "title": "French" }
+    ]
+}
+```
+
+**Expected Result**
+
+At runtime, the application is going to display languages provided by the extension (given that no other extension file replaces the values, otherwise it is going to be a "last wins" scenario)
+
+```json
+{
+    "languages": [
+        { key: "fr", "title": "French" }
+    ]
+}
+```
+
 ### Routes
 
 The `routes` array in the config contains objects like those shown in the