From 613e2bfe03fc212e8c35e0340a597b5edf8d3b7c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= <freben@gmail.com>
Date: Thu, 22 Feb 2024 11:54:39 +0100
Subject: [PATCH] extend the visibility docs with deep visibility
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Fredrik Adelöw <freben@gmail.com>
---
 docs/conf/defining.md | 42 +++++++++++++++++++++++++++++++++---------
 1 file changed, 33 insertions(+), 9 deletions(-)

diff --git a/docs/conf/defining.md b/docs/conf/defining.md
index 9e13442f7b..1c2fb8d273 100644
--- a/docs/conf/defining.md
+++ b/docs/conf/defining.md
@@ -84,13 +84,16 @@ receive schema validation and autocompletion. For example:
 ## Visibility
 
 The `https://backstage.io/schema/config-v1` meta schema is a superset of JSON
-Schema Draft 07. The single addition is a custom `visibility` keyword, which is
-used to indicate whether the given config value should be visible in the
-frontend or not. The possible values are `frontend`, `backend`, and `secret`,
-where `backend` is the default. A visibility of `secret` has the same scope at
-runtime, but it will be treated with more care in certain contexts, and defining
-both `frontend` and `secret` for the same value in two different schemas will
-result in an error during schema merging.
+Schema Draft 07. The only additions are the custom `visibility` and
+`deepVisibility` keywords, which are used to indicate whether the given config
+value should be visible in the frontend or not. The `visibility` marker applies
+only to the field it's on, while the `deepVisibility` marker applies to the
+field it's on and downwards in the hierarchy as well. The possible values are
+`frontend`, `backend`, and `secret`, where `backend` is the default. A
+visibility of `secret` has the same scope at runtime, but it will be treated
+with more care in certain contexts, and defining both `frontend` and `secret`
+for the same value in two different schemas will result in an error during
+schema merging.
 
 The visibility only applies to the direct parent of where the keyword is placed
 in the schema. For example, if you set the visibility to `frontend` for a subset
@@ -105,17 +108,38 @@ declare the visibility of a leaf node of `type: "string"`.
 | `backend`    | (Default) Only in backend                                          |
 | `secret`     | Only in backend and may be excluded from logs for security reasons |
 
-You can set visibility with an `@visibility` comment in the `Config` Typescript
-interface.
+You can set visibility with a `@visibility` or `@deepVisibility` comment in the
+`Config` Typescript interface.
 
 ```ts
 export interface Config {
   app: {
     /**
      * Frontend root URL
+     * NOTE: Visibility applies to only this field
      * @visibility frontend
      */
     baseUrl: string;
+
+    /**
+     * Some custom complex type
+     * NOTE: Visibility applies recursively downward
+     * This is particularly useful for complex types like durations
+     * @deepVisibility frontend
+     */
+    customSchedule: HumanDuration;
+  };
+
+  backend: {
+    /**
+     * Some custom credentials type
+     * NOTE: Visibility applies recursively downward, and this would NOT have
+     * been safe if the regular visibility keyword had been used
+     * @deepVisibility secret
+     */
+    customCredentials: {
+      password: string;
+    };
   };
 }
 ```