Settings and Sensitive Values

Lombok apps declare structured, user-editable configuration in the settings block of the app manifest (config.json). The platform uses this block to:

render a settings form for the app
validate values written back by users or by the app itself
resolve effective values across scopes
mask the values of keys that look sensitive when reading them back

This page is a reference for that block as modeled in the app types (appSettingsConfigSchema and the JsonSchema07* schemas).

The `settings` block

{
  "settings": {
    "secretKeyPattern": "^(api_key|secret|token)",
    "user": {
      /* JSON Schema 07 object */
    },
    "folder": {
      /* JSON Schema 07 object */
    },
  },
}

Field	Type	Notes
`secretKeyPattern`	`string` (regex)	Optional. Marks likely-sensitive keys.
`user`	JSON Schema 07 object	Optional. Schema for user-scoped settings.
`folder`	JSON Schema 07 object	Optional. Schema for folder-scoped settings.

At least one of user or folder must be present. A settings block with neither is rejected at install time.

Scopes: user vs folder

Settings live in two independent scopes, each with its own schema:

User — configuration tied to a user
Folder — configuration tied to a folder the app operates on

An app may define one or both. The two schemas do not need to share keys.

Effective value resolution

When the platform reads settings, it computes an effective value per key. For folder-scoped reads the cascade is:

folder value  →  user value  →  schema default  →  (omitted)

For user-scoped reads there is no folder layer, so it is simply:

user value  →  schema default  →  (omitted)

Keys with no stored value and no default are omitted from the result rather than returned as null. Alongside the resolved values, reads return a sources map indicating where each key came from: folder, user, or default.

Setting keys

Setting keys must match:

/^[a-z0-9](?:[a-z0-9_]*[a-z0-9])?$/

That is: lowercase a–z, digits 0–9, and underscores; they must not start or end with an underscore. This is enforced on schema properties and on incoming writes.

The schema for each scope

Each scope is a JSON Schema 07 object:

{
  "type": "object",
  "properties": {
    /* key -> property schema */
  },
  "patternProperties": {
    /* "^prefix_" -> property schema */
  },
  "required": [
    /* keys */
  ],
}

Lombok accepts a deliberately constrained subset of JSON Schema 07. The accepted property types are below.

Primitive properties

All primitives share description and default (optional). Type-specific constraints:

Type	Extra fields
`string`	`enum`, `minLength`, `maxLength`, `pattern`
`number`	`minimum`, `maximum`
`integer`	`minimum`, `maximum`
`boolean`	—

Nullable fields

Any primitive type may be written as a two-element tuple like ["string", "null"] to mark the field nullable.

Array properties

Arrays support:

primitive items
object items
discriminated object items via oneOf

Nested object properties

A property may itself be an object with nested properties, optional additionalProperties, and required.

`patternProperties`

In addition to fixed properties, a scope may declare patternProperties to accept a family of keys sharing a prefix. The regex string itself must match:

/^\^[a-z0-9][a-z0-9_]*_$/

For example: "^provider_".

Reading and writing values

Values are read and written through the platform, not stored directly in the manifest:

REST — user/folder custom-settings GET/PATCH endpoints
Worker SDK — custom settings read/write helpers

A read returns:

{ values, sources, schema, secretKeyPattern }

Write semantics

each key in a patch is validated against its property schema
unknown keys and malformed keys are rejected
null deletes a key
the total stored size per scope per app is capped at 64 KB
successful user-scope writes broadcast a settings_changed event

Sensitive values: `secretKeyPattern`

secretKeyPattern is a regex used to identify keys that should be treated as sensitive by naming convention. When settings are read back, the value of matching keys is replaced with:

********

Masking applies to top-level secret keys and to matching keys nested inside arrays of objects.

[!NOTE] secretKeyPattern is a masking and identification mechanism, not a vault or encryption system. It helps avoid echoing likely-secret values back into forms and responses, but it does not change how values are stored.

Worked example

The simple demo app declares both scopes and a secret pattern:

{
  "settings": {
    "secretKeyPattern": "^(api_key|secret|token)",
    "user": {
      "type": "object",
      "properties": {
        "api_key": {
          "type": "string",
          "description": "API key for external service",
        },
        "max_retries": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100,
          "default": 3,
        },
        "theme": {
          "type": "string",
          "enum": ["light", "dark"],
          "default": "light",
        },
      },
      "required": ["api_key"],
    },
    "folder": {
      "type": "object",
      "properties": {
        "auto_index": { "type": "boolean", "default": true },
      },
    },
  },
}