From 648ab6764fc30c0b8daf0d73cdbbdaf106f522e2 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Thu, 15 Aug 2024 15:23:30 +0200
Subject: [PATCH] docs/frontend-system: docs for how to override config schema

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
---
 .../architecture/25-extension-overrides.md    | 34 +++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/docs/frontend-system/architecture/25-extension-overrides.md b/docs/frontend-system/architecture/25-extension-overrides.md
index 8b6d87bc81..5e55ef3d0e 100644
--- a/docs/frontend-system/architecture/25-extension-overrides.md
+++ b/docs/frontend-system/architecture/25-extension-overrides.md
@@ -136,6 +136,40 @@ const myOverrideExtension = myExtension.override({
 });
 ```
 
+## Overriding configuration schema
+
+Overriding the configuration schema works very similar to overriding the declared inputs. You can define new configuration fields that will be merged with the existing ones, but you can not re-declare existing fields. The following example shows how to override an extension and add a new configuration field:
+
+```tsx
+// Original extension
+const exampleExtension = createExtension({
+  name: 'example',
+  config: {
+    schema: {
+      layout: z => z.enum(['grid', 'list']).optional(),
+    },
+  },
+  output: [coreExtensionData.reactElement],
+  factory: ({ config }) => [
+    coreExtensionData.reactElement(<MyExtension layout={config.layout} />),
+  ],
+});
+
+const overrideExtension = exampleExtension.override({
+  config: {
+    schema: {
+      additionalField: z => z.string().optional(),
+    },
+  },
+  factory(originalFactory, { config }) {
+    console.log(
+      `additionalField=${config.additionalField} layout=${config.layout}`,
+    );
+    return originalFactory();
+  },
+});
+```
+
 ## Override App Extensions
 
 In order to override an app extension, you must create a new extension and add it to the list of overridden features. The steps are: create your extension overrides and use them in Backstage.