docs: add docs for configuration schema

docs/conf/defining.md

@@ -4,16 +4,109 @@ title: Defining Configuration for your Plugin
 description: Documentation on Defining Configuration for your Plugin
 ---
 
-There is currently no tooling support or helpers for defining plugin
-configuration. But it's on the roadmap.
+Configuration in Backstage is organized via a configuration schema, which in
+turn is defined using a super set of
+[JSON Schema Draft-07](https://json-schema.org/specification-links.html#draft-7).
+Each plugin or package within a Backstage app can contribute to the schema,
+which during validation is stitched together into a single schema.
 
-Meanwhile, document the config values that you are reading in your plugin
-README.
+## Schema Collection and Definition
 
-## Format
+Schemas are collected from all packages and dependencies in each repo that are a
+part of the Backstage ecosystem, including transitive dependencies. The current
+definition of "part of the ecosystem" is that a package has at least one
+dependency in the `@backstage` namespace, but this is subject to change.
+
+Each package is search for schema at a single point of entry, a top-level
+`"configSchema"` field in `package.json`. The field can either contain an
+inlined JSON schema, or a relative path to a schema file. Supported schema file
+formats are `.json` or `.d.ts`.
+
+> When using a schema file, be sure to include the file in your `package.json` >
+> `"files"` field as well!
+
+TypeScript configuration schema files should export a single `Config` type, for
+example:
+
+```ts
+export interface Config {
+  app: {
+    /**
+     * Frontend root URL
+     * @visibility frontend
+     */
+    baseUrl: string;
+  };
+}
+```
+
+Separate `.json` schema files can use a top-level
+`"$schema": "https://backstage.io/schema/config-v1"` declaration in order to
+receive schema validation and autocompletion. For example:
+
+```json
+{
+  "$schema": "https://backstage.io/schema/config-v1",
+  "type": "object",
+  "properties": {
+    "app": {
+      "type": "object",
+      "properties": {
+        "baseUrl": {
+          "type": "string",
+          "description": "Frontend root URL",
+          "visibility": "frontend"
+        }
+      },
+      "required": ["baseUrl"]
+    },
+    "required": ["app"]
+  }
+}
+```
+
+## Visibility
+
+The `https://backstage.io/schema/config-v1` meta schema is a super set 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`, `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
+of the schema with `type: "object"`, but none of the descendants, only an empty
+object will be available in the frontend. The full ancestry does not need to
+have correctly defined visibilities however, so it is enough to only for example
+declare the visibility of a leaf node of `type: "string"`.
+
+## Validation
+
+Schema can be validated using the `backstage-cli config:validate` command. If
+you want to validate anything else than the default `app-config.yaml`, be sure
+to pass in all of the configuration files as `--config <path>` options as well.
+
+To validate and examine the frontend configuration, use can use the
+`backstage-cli config:print --frontend` command. Just like for validation you
+may need to pass in all files using one or multiple `--config <path>` options.
+
+## Guidelines
+
+> Limit static configuration. The first question to ask is whether a particular
+> option actually needs to be static configuration, or if it might just as well
+> be a TypeScript API. In general options that you want to be able to change for
+> different deployment environments should be static configuration, while it
+> should otherwise be avoided.
 
 When defining configuration for your plugin, keep keys camelCased and stick to
 existing casing conventions such as `baseUrl`.
 
 It is also usually best to prefer objects over arrays, as it makes it possible
 to override individual values using separate files or environment variables.
+
+Avoid creating new top-level fields as much as possible. Either place your
+configuration within an existing known top-level block, or create a single new
+one using e.g. the name of the product that the plugin integrates.

docs/conf/index.md

@@ -33,6 +33,20 @@ values that are common between the two only need to be defined once. Such as the
 
 For more details, see [Writing Configuration](./writing.md).
 
+## Configuration Schema
+
+The configuration is validated using a JSON Schema definitions. Each plugin and
+package can provide pieces of the configuration schema, which is stitched
+together to form a complete schema during validation. The configuration schema
+is also used to select what configuration is available in the frontend using a
+custom `visibility` keyword, as configuration is by default only available in
+the backend.
+
+You can validate your configuration against the schema using
+`backstage-cli config:validate`, and define schema for your own plugin either
+using JSON Schema or TypeScript. For more information, see
+[Defining Configuration](./defining.md).
+
 ## Reading Configuration
 
 As a plugin developer, you likely end up wanting to define configuration that
@@ -49,5 +63,5 @@ More details are provided in dedicated sections of the documentation.
   plugin.
 - [Writing Configuration](./writing.md): How to provide configuration for your
   Backstage deployment.
-- [Defining Configuration](./defining.md): How to define configuration for users
-  of your plugin.
+- [Defining Configuration](./defining.md): How to define configuration schema
+  for users of your plugin or package.

docs/conf/writing.md

@@ -97,10 +97,10 @@ order:
 - If no config flags are provided, `app-config.local.yaml` has higher priority
   than `app-config.yaml`.
 
-## Secrets
+## Secrets and Dynamic Data
 
-Secrets are supported via special secret keys that are prefixed with `$`, which
-in turn provide a number of different ways to read in secrets. To load a
+Secrets are supported via special data loading keys that are prefixed with `$`,
+which in turn provide a number of different ways to read in secrets. To load a
 configuration value as a secret, supply an object with one of the special secret
 keys, for example `$env` or `$file`. A full list of supported secret keys can be
 found below. For example, the following will read the config key
@@ -117,10 +117,6 @@ will return the value of the environment variable `MY_SECRET_KEY` when the
 backend started up. All secrets are loaded at startup, so changing the contents
 of secret files or environment variables will not be reflected at runtime.
 
-Note that secrets will never be included in the frontend bundle or development
-builds. When loading configuration you have to explicitly enable reading of
-secrets, which is only done for the backend configuration.
-
 As hinted at, secrets can be loaded from a bunch of different sources, and can
 be extended with more. Below is a list of the currently supported methods for
 loading secrets.