From 6e385a527db6088bb6365d8682156600563edec7 Mon Sep 17 00:00:00 2001
From: cinereal <cinereal@riseup.net>
Date: Mon, 2 Jun 2025 15:44:53 +0200
Subject: [PATCH] add sample configuration schema

---
 architecture.md | 154 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 154 insertions(+)

diff --git a/architecture.md b/architecture.md
index 893120d..b622c00 100644
--- a/architecture.md
+++ b/architecture.md
@@ -220,6 +220,160 @@ Whereas the core abstraction in Fediversity is a NixOS configuration module, a m
 
 ![](https://git.fediversity.eu/Fediversity/meta/raw/branch/main/architecture-docs/host-architecture.png)
 
+
+### Sample configuration schema
+
+Whereas Nix(OS) option modules use Nix to specify types, in order to communicate the expected schema to other tools such as web applications, we use [JSON Schema](https://json-schema.org/) as an intermediate format, building upon [earlier work converting between such schemas by Nix collective Clan](https://clan.lol/blog/json-schema-converter/).
+An example of such a schema might looks as follows:
+
+```json
+{
+  "$exportedModuleInfo": {
+    "path": []
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "domain": {
+      "$exportedModuleInfo": {
+        "path": [
+          "domain"
+        ]
+      },
+      "default": "fediversity.net",
+      "description": "Apex domain under which the services will be deployed.\n",
+      "enum": [
+        "fediversity.net"
+      ]
+    },
+    "enable": {
+      "$exportedModuleInfo": {
+        "path": [
+          "enable"
+        ]
+      },
+      "default": false,
+      "description": "Whether to enable Fediversity configuration.",
+      "examples": [
+        true
+      ],
+      "type": "boolean"
+    },
+    "initialUser": {
+      "$exportedModuleInfo": {
+        "path": [
+          "initialUser"
+        ]
+      },
+      "default": null,
+      "description": "Some services require an initial user to access them.\nThis option sets the credentials for such an initial user.\n",
+      "oneOf": [
+        {
+          "type": "null"
+        },
+        {
+          "$exportedModuleInfo": {
+            "path": [
+              "initialUser"
+            ]
+          },
+          "additionalProperties": false,
+          "properties": {
+            "displayName": {
+              "$exportedModuleInfo": {
+                "path": [
+                  "initialUser",
+                  "displayName"
+                ]
+              },
+              "description": "Display name of the user",
+              "type": "string"
+            },
+            "email": {
+              "$exportedModuleInfo": {
+                "path": [
+                  "initialUser",
+                  "email"
+                ]
+              },
+              "description": "User's email address",
+              "type": "string"
+            },
+            "password": {
+              "$exportedModuleInfo": {
+                "path": [
+                  "initialUser",
+                  "password"
+                ]
+              },
+              "description": "Password for login",
+              "type": "string"
+            },
+            "username": {
+              "$exportedModuleInfo": {
+                "path": [
+                  "initialUser",
+                  "username"
+                ]
+              },
+              "description": "Username for login",
+              "type": "string"
+            }
+          },
+          "required": [
+            "displayName",
+            "email",
+            "password",
+            "username"
+          ],
+          "type": "object"
+        }
+      ]
+    },
+    "forgejo": {
+      "$exportedModuleInfo": {
+        "path": [
+          "forgejo"
+        ]
+      },
+      "default": null,
+      "description": "Configuration for the Forgejo service\n",
+      "oneOf": [
+        {
+          "type": "null"
+        },
+        {
+          "$exportedModuleInfo": {
+            "path": [
+              "forgejo"
+            ]
+          },
+          "additionalProperties": false,
+          "properties": {
+            "enable": {
+              "$exportedModuleInfo": {
+                "path": [
+                  "forgejo",
+                  "enable"
+                ]
+              },
+              "default": false,
+              "description": "Whether to enable Forgejo.",
+              "examples": [
+                true
+              ],
+              "type": "boolean"
+            }
+          },
+          "type": "object"
+        }
+      ]
+    }
+  },
+  "type": "object"
+}
+```
+
 ## Break-down of project milestones
 
 Whereas details of the implementation may need to be decided as the technical challenges involved become clear, we can already give a higher-level planning of relevant milestones and some of their salient features: