Gitpulse
Merged
Size
XL
Change Breakdown
Feature80%
Docs20%
#60067feat(config): add rich description fields to JSON Schema output [AI-assisted]

Config schema gains 814 field descriptions

Config schema gains 814 field descriptions
SO
solavrc
·Apr 4, 2026

The `openclaw config schema` command now exposes descriptions for all ~814 configuration fields, turning a bare schema into a self-documenting reference that IDEs and AI tools can actually read.

Configuration schemas have always been cryptic. Developers running openclaw config schema got a valid JSON Schema document, but it was silent on what each field actually did. Tooltips stayed empty. Autocomplete offered no hints. AI assistants parsing the schema had nothing to work with.

That's changing now. A post-processing step walks the generated schema tree and applies field documentation from existing FIELD_HELP and FIELD_LABELS maps—resources that were already powering the Control UI and lookup API but had never made it into the schema output itself. The result: ~814 description fields appear where there were previously zero.

The change touches the schema generation pipeline in the config package. Existing descriptions from Zod's .describe() are preserved and not overwritten. The system handles nested properties, wildcard keys like models.providers.*, array item paths using both [] and * notation, and composition branches with anyOf/oneOf/allOf.

This work sits within a broader initiative (#22278) to publish the schema to a stable URL. With rich descriptions now embedded, that published schema becomes genuinely useful—editors can show tooltips, CI can validate configs against real documentation, and AI tools get meaningful field context.

View Original GitHub Description

Summary

  • Problem: openclaw config schema generates a JSON Schema with zero description fields, despite the codebase maintaining comprehensive FIELD_HELP (~651 entries) and FIELD_LABELS (~676 entries) maps already used by the Control UI and config.schema.lookup API.
  • Why it matters: Without descriptions, IDE auto-complete shows no tooltips, the schema is not self-documenting, and LLM/AI tools consuming the schema get no field documentation.
  • What changed: Post-processing step in schema-base.ts walks the generated JSON Schema tree and applies descriptions from merged FIELD_HELP/FIELD_LABELS. ~814 descriptions added (previously 0).
  • What did NOT change: No Zod schema modifications, no runtime config validation changes, no new dependencies.

Change Type (select all)

  • Bug fix
  • Feature
  • Refactor required for the fix
  • Docs
  • Security hardening
  • Chore/infra

Scope (select all touched areas)

  • Gateway / orchestration
  • Skills / tool execution
  • Auth / tokens
  • Memory / storage
  • Integrations
  • API / contracts
  • UI / DX
  • CI/CD / infra

Linked Issue/PR

  • Closes #60068
  • Related #22278
  • This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

N/A — new feature.

Regression Test Plan (if applicable)

N/A — new feature. Existing schema tests (32 tests across 4 files) cover the generated schema structure and ensure no regression.

User-visible / Behavior Changes

  • openclaw config schema output now includes description fields on ~814 properties (previously 0)
  • config.schema.lookup behavior unchanged (descriptions were already in hints)
  • VS Code users can point $schema at the output for rich tooltips

Diagram (if applicable)

Before:
openclaw config schema -> JSON Schema (no descriptions)

After:
openclaw config schema -> JSON Schema -> applyDescriptions(FIELD_HELP ∪ FIELD_LABELS) -> JSON Schema (814 descriptions)

Security Impact (required)

  • New permissions/capabilities? No
  • Secrets/tokens handling changed? No
  • New/changed network calls? No
  • Command/tool execution surface changed? No
  • Data access scope changed? No

Repro + Verification

Environment

  • OS: macOS 15.4 (arm64)
  • Runtime: Node.js v22.17.0
  • Model/provider: N/A
  • Integration/channel: N/A

Steps

  1. Run openclaw config schema and count description fields
  2. Before: 0 descriptions
  3. After: ~814 descriptions

Expected

Schema properties have description fields from FIELD_HELP/FIELD_LABELS.

Actual

Confirmed — 814 description fields present in generated schema.

Evidence

  • Failing test/log before + passing after
  • Trace/log snippets

All 32 schema tests pass (4 test files). Generated schema validated locally.

Human Verification (required)

  • Verified scenarios: Generated schema loaded in VS Code with $schema directive; tooltips display rich descriptions for gateway.port, logging.level, agents.defaults.compaction.mode, etc.
  • Edge cases checked: Zod .describe() descriptions preserved (not overwritten); composition branches (anyOf/oneOf/allOf) traversed; both [] and * array item path aliases matched.
  • What was not verified: Full end-to-end with Control UI (descriptions flow through uiHints, not the schema itself, so no impact expected).

Review Conversations

  • I replied to or resolved every bot review conversation I addressed in this PR.
  • I left unresolved only the conversations that still need reviewer or maintainer judgment.

Codex review feedback addressed:

  1. Composition branch traversal (anyOf/oneOf/allOf) — implemented
  2. Wildcard * alias for array items — implemented

Compatibility / Migration

  • Backward compatible? Yes
  • Config/env changes? No
  • Migration needed? No

Risks and Mitigations

  • Risk: Generated schema file size increases (~1540 lines added to schema.base.generated.ts)
    • Mitigation: Descriptions are already maintained in FIELD_HELP/FIELD_LABELS; this just surfaces them in a different output format. No runtime memory impact (schema is generated at build time).
© 2026 · via Gitpulse