Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix feat: add description fields to `openclaw config schema` JSON Schema output [1 pull requests, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#60068•Fetched 2026-04-08 02:36:51
View on GitHub
Comments
0
Participants
1
Timeline
3
Reactions
1
Author
solavrcsolavrc
Participants
solavrcsolavrc
Timeline (top)
closed ×1cross-referenced ×1locked ×1

Fix Action

Fixed

PR fix notes

PR #60067: feat(config): add rich description fields to JSON Schema output [AI-assisted]

Description (problem / solution / changelog)

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. ~769 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 (28 tests across 3 files) cover the generated schema structure and ensure no regression.

User-visible / Behavior Changes

  • openclaw config schema output now includes description fields on ~769 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 (769 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. openclaw config schema | python3 -c "import json,sys; s=json.load(sys.stdin); print(sum(1 for _ in str(s).split(chr(39)+chr(100)+chr(101)+chr(115)+chr(99)+chr(114)+chr(105)+chr(112)+chr(116)+chr(105)+chr(111)+chr(110)+chr(39))))"
  2. Before: 0 descriptions
  3. After: ~769 descriptions

Expected

Schema properties have description fields from FIELD_HELP/FIELD_LABELS.

Actual

Confirmed — 769 description fields present in generated schema.

Evidence

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

All 28 schema tests pass. Generated schema validated as valid JSON Schema Draft-07 via jsonschema Python library.

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
  3. Greptile test assertion tightening — implemented

Compatibility / Migration

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

Risks and Mitigations

  • Risk: Generated schema file size increases (~1500 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).

Changed files

  • src/cli/gateway-cli/run.option-collisions.test.ts (modified, +10/-3)
  • src/config/schema-base.ts (modified, +95/-0)
  • src/config/schema.base.generated.ts (modified, +1486/-1)
  • src/config/schema.test.ts (modified, +6/-1)
RAW_BUFFERClick to expand / collapse

Problem

openclaw config schema generates a JSON Schema with zero description fields on any property. This means:

  • No IDE auto-complete hints in VS Code when editing openclaw.json
  • No self-documenting schema — users must guess what each field does
  • Third-party tools consuming the schema get no field documentation

Current State

The codebase already maintains a comprehensive FIELD_LABELS map in src/config/schema.labels.ts with 500+ human-readable labels keyed by dot-path (e.g. "gateway.port" → "Gateway Port"). These labels are used by the Control UI but are not applied to the JSON Schema output.

Additionally, a few Zod schemas already use .describe() (9 instances across zod-schema.agent-defaults.ts and zod-schema.providers-core.ts), which do produce descriptions, but the vast majority of fields have none.

Proposed Solution

Apply FIELD_LABELS as description values in the generated JSON Schema as a post-processing step after OpenClawSchema.toJSONSchema(). This requires:

  1. Walking the JSON Schema tree and building dot-paths
  2. Matching paths to FIELD_LABELS entries
  3. Setting description only when not already present (preserving Zod .describe())
  4. Handling nested properties, wildcards (*), and array items ([])

Implementation

PR: #60067

Benefit

With descriptions in the schema, users get:

  • VS Code tooltips on every config key
  • Better openclaw config schema output for documentation
  • Self-documenting schema for LLM/AI tools that consume the schema

Related: #22278 (broader schema publishing initiative)

extent analysis

TL;DR

Apply the existing FIELD_LABELS map to the generated JSON Schema as a post-processing step to add descriptive fields.

Guidance

  • Review the FIELD_LABELS map in src/config/schema.labels.ts to ensure it covers all necessary fields and is up-to-date.
  • Implement a recursive function to walk the JSON Schema tree, building dot-paths and matching them to FIELD_LABELS entries.
  • When applying descriptions, check if a description already exists (e.g., from Zod's .describe()) and only add a new description if one is not present.
  • Consider handling edge cases such as nested properties, wildcards (*), and array items ([]) separately to ensure correct description application.

Example

// Pseudo-example of applying FIELD_LABELS to JSON Schema
const jsonSchema = OpenClawSchema.toJSONSchema();
const fieldLabels = FIELD_LABELS;

function applyDescriptions(schema: any, path: string) {
  // Recursively walk the schema and apply descriptions
  if (schema.properties) {
    Object.keys(schema.properties).forEach((key) => {
      const fullPath = `${path}.${key}`;
      if (fieldLabels[fullPath] && !schema.properties[key].description) {
        schema.properties[key].description = fieldLabels[fullPath];
      }
      applyDescriptions(schema.properties[key], fullPath);
    });
  }
}

applyDescriptions(jsonSchema, '');

Notes

This approach assumes that the FIELD_LABELS map is comprehensive and accurately reflects the desired descriptions for each field. Additionally, the implementation should handle cases where Zod's .describe() has already added descriptions to avoid overwriting them.

Recommendation

Apply workaround: Implement the proposed solution by applying the FIELD_LABELS map to the generated JSON Schema as a post-processing step, as this will provide the necessary descriptions for users and third-party tools without requiring significant changes to the existing codebase.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#generation error#database connection#vector store#embedding generation#cache error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING