tags: api/syscall references:
The Config API provides functions for managing configuration values, defining their JSON schemas, and exposing them in the [Configuration Manager](Configuration Manager) UI.
config.define(key, schema)
Defines a JSON schema for a configuration key.
Parameters:
key (string) — Configuration key.schema (table) — JSON Schema definition; default applies a missing value and ui annotations expose it in the Configuration Manager.Example:
config.define("shortWikiLinks", {
description = "Render short wiki link labels",
type = "boolean",
default = true,
ui = {category = "Editor", label = "Short wiki links", priority = 1},
})
config.defineCategory(definition)
Defines or updates a Configuration Manager UI category.
Parameters:
definition (table) — Category name, description, and priority.Example:
config.defineCategory {
name = "Editor",
description = "Page editor behavior.",
priority = 50,
}
config.get(path, defaultValue)
Gets a configuration value by path, with dot notation support.
Parameters:
path (string) — Configuration path.defaultValue — Value returned when the path is absent.Returns:
Example:
local theme = config.get("theme", "light")
config.getCategories()
Gets all Configuration Manager UI categories.
Returns:
table — Category definitions keyed by name.config.getSchemas()
Gets all defined configuration schemas.
Returns:
table — Schemas keyed by configuration path.config.getValues()
Gets all configuration values as a single table.
Returns:
table — All configuration values.config.has(path)
Checks whether a configuration path exists.
Parameters:
path (string) — Configuration path.Returns:
boolean — Whether the path exists.config.insert(path, value)
Appends a value to the configuration array at a path.
Parameters:
path — Configuration path.value — Value to append.config.set(path, value)
config.set(values)
Sets one configuration value or multiple values at once.
Parameters:
pathOrValues — Configuration path or table of values.value? — Value to set when a path is supplied.Examples:
config.set("theme", "dark")
config.set({theme = "dark", fontSize = 14})
config.setLuaValue(path, value)
config.setLuaValue(values)
Sets configuration while preserving the supplied Lua value representation.
Parameters:
pathOrValues — Configuration path or table of values.value? — Lua value to preserve.Schemas registered through config.define support two extensions on top of plain JSON Schema:
default: when present, the value is automatically applied if the key is not already set.ui: optional annotations that expose the field in the [Configuration Manager](Configuration Manager).ui annotationsOnly fields that have a ui attribute appear in the [Configuration Manager](Configuration Manager). Recognized properties:
category (required): name of the category (tab) the field appears under. It should match a config.defineCategory name; otherwise the category appears at the bottom in alphabetical order.label: human-readable label shown next to the control.priority: number used to sort fields within a category in descending order. Fields without a priority sort as 0.inputType: for string fields, set this to "password" to render a masked input.The control shown depends on the schema type:
boolean: checkboxstring with enum: dropdownstring: text input, or password input when ui.inputType is "password"number: number inputThe field's description is shown as helper text below the label.
Nested schemas can carry their own ui annotations. When a parent object's children all have ui set, the parent itself is skipped and each child appears as an individual field. This is how related options such as smartQuotes.double.left and smartQuotes.double.right become separate rows in the same category.
Registered categories appear in descending priority, with higher values first. A category's optional description appears at the top of the category. Categories referenced by a schema but never registered appear after registered categories in alphabetical order.