From 64c487660c09c846143284e3210b9987cf5251e5 Mon Sep 17 00:00:00 2001
From: Lars Mueller <appgurulars@gmx.de>
Date: Wed, 31 Mar 2021 22:36:03 +0200
Subject: [PATCH] Basic schema docs, focus on non-string entry traps

---
 Readme.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/Readme.md b/Readme.md
index 8f1e3e5..6a50321 100644
--- a/Readme.md
+++ b/Readme.md
@@ -125,6 +125,54 @@ custom_bluon:write(userdata(), rope)
 assert(rope:to_text() == "\100userdata")
 ```
 
+### Schema
+
+Place a file `schema.lua` in your mod, returning a schema table.
+
+#### Non-string entries and `minetest.conf`
+
+Suppose you have the following schema:
+
+```lua
+return {
+	type = "table",
+	entries = {
+		[42] = {
+			type = "boolean",
+			description = "The Answer"
+			default = true
+		}
+	}
+}
+```
+
+And a user sets the following config:
+
+```conf
+mod.42 = false
+```
+
+It won't work, as the resulting table will be `{["42"] = false}` instead of `{[42] = false}`. In order to make this work, you have to convert the keys yourself:
+
+```lua
+return {
+	type = "table",
+	keys = {
+		-- this will convert all keys to numbers
+		type = "number"
+	},
+	entries = {
+		[42] = {
+			type = "boolean",
+			description = "The Answer"
+			default = true
+		}
+	}
+}
+```
+
+This is best left explicit. First, you shouldn't be using numbered field keys if you want decent `minetest.conf` support, and second, `modlib`'s schema module could only guess in this case, attempting conversion to number / boolean. What if both number and string field were set as possible entries? Should the string field be deleted? And so on.
+
 ## Configuration
 
 ### Legacy