Skip to content

[plan] Improve schema metadata and documentation quality #8132

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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions