Skip to content

[plan] Improve config field naming and schema documentation #6349

Closed as not planned

Description

@github-actions

Objective

Add schema descriptions and documentation to clarify the three different config field contexts in the schema hierarchy.

Context

The generic name "config" appears at multiple nesting levels:

  1. $defs.engine_config.oneOf[1].config - Engine-specific configuration
  2. sandbox.oneOf[1].agent.oneOf[2].config - Agent sandbox configuration
  3. sandbox.oneOf[1].config - General sandbox configuration

The generic name is ambiguous without full field path context.

Approach

  1. Add schema description fields clarifying each config context
  2. Include hierarchy information in descriptions (e.g., "Engine-specific config nested under engine.config")
  3. Document the config field hierarchy with examples
  4. Consider recommending more specific field names in future schema versions (document in CHANGELOG or migration guide)

Files to Modify

  • Update: pkg/parser/schemas/workflow.schema.json (add descriptions with hierarchy context)
  • Update: docs/src/content/docs/reference/engine.md (document engine config)
  • Update: docs/src/content/docs/reference/sandbox.md (document both sandbox config contexts)
  • Optional: Add note to CHANGELOG.md about potential future field naming improvements

Acceptance Criteria

AI generated by Plan Command for discussion #6312

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions