Skip to content

[plan] Improve schema metadata and documentation quality #8132

@github-actions

Description

@github-actions

Overview

This tracking issue covers improvements to schema metadata and documentation quality identified in the December 29, 2025 schema audit.

Source: Discussion #8130

The audit identified 8 issues (2 critical, 6 moderate) across our three schema files. While internal consistency is excellent (100% root descriptions, all $defs used, strong validation), we need to improve metadata and example coverage for better IDE integration and developer experience.

Planned Tasks

This work is broken down into 5 focused sub-issues:

  1. Add top-level metadata to all schemas - Critical for IDE integration and schema identification
  2. Add applyTo field description - Complete missing root-level documentation
  3. Add examples to major workflow fields - Improve discoverability of key features
  4. Add examples to MCP schema - Currently has zero examples despite complexity
  5. Improve schema validation constraints - Convert single-value enums and add format constraints

Context

All identified issues have persisted since the November 2025 audit (no regression, but no improvement either). These improvements will:

  • Enhance IDE autocomplete and inline documentation
  • Support schema versioning and evolution tracking
  • Improve developer onboarding and discoverability
  • Strengthen validation with better constraints

Priority

AI generated by Plan Command for discussion #8130

Sub-issues

Metadata

Metadata

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions