[Schema Consistency] Schema Consistency Check - 2026-01-03

[github-actions[bot]]

Summary

Strategy Used: Cross-Schema Consistency & Type Analysis (Strategy-004)
Inconsistencies Found: 5 (1 critical, 4 moderate)
New Issues: 0 (all persistent from previous runs)
Status: Regression validation - confirms known issues still present

This analysis compared the three schemas (main_workflow_schema.json, included_file_schema.json, mcp_config_schema.json) to find inconsistencies in type definitions, $defs, field scope, and default values.

Full Report

Critical Issues

1. MCP Version Type Inconsistency (PERSISTENT)

Issue: The version field in MCP tool definitions has inconsistent type definitions across schemas.

Evidence:

• main_workflow_schema.json: $defs.stdio_mcp_tool.properties.version accepts ["string", "number"]
• included_file_schema.json: $defs.stdio_mcp_tool.properties.version accepts ["string", "number"]
• mcp_config_schema.json: properties.version accepts only "string"

Implementation Reality: The compiler at pkg/workflow/mcp_servers.go:getGitHubDockerImageVersion() explicitly handles multiple numeric types:

switch v := versionSetting.(type) {
case string:
    githubDockerImageVersion = v
case int:
    githubDockerImageVersion = fmt.Sprintf("%d", v)
case int64:
    githubDockerImageVersion = fmt.Sprintf("%d", v)
case uint64:
    githubDockerImageVersion = fmt.Sprintf("%d", v)
case float64:
    githubDockerImageVersion = fmt.Sprintf("%g", v)
}

Impact:

• Users of mcp_config_schema.json cannot use numeric versions (e.g., version: 20, version: 3.11)
• Schema validation would reject valid configurations that the implementation accepts
• API surface mismatch between schema definition and runtime behavior

Recommendation: Update mcp_config_schema.json to accept ["string", "number"] like the other two schemas.

File: pkg/parser/schemas/mcp_config_schema.json:12

---

Moderate Issues

2. stdio_mcp_tool $comment Documentation Missing in Included Schema (PERSISTENT)

Issue: The included schema is missing 780 bytes of validation constraint documentation that exists in the main schema.

Evidence:

• main_workflow_schema.json $defs.stdio_mcp_tool.$comment:

  "Validation constraints: (1) Mutual exclusion: 'command' and 'container' cannot 
  both be specified. (2) Requirement: Either 'command' or 'container' must be 
  provided (via 'anyOf'). (3) Dependency: 'network' requires 'container' 
  (validated in 'allOf'). (4) Type constraint: When 'type' is 'stdio' or 'local', 
  either 'command' or 'container' is required."
  

• included_file_schema.json: No $comment field

Impact:

• Developers reading included schema miss validation logic documentation
• Inconsistent documentation quality across schemas
• 780-byte size difference between definitions

Recommendation: Add the same $comment field to included_file_schema.json $defs.stdio_mcp_tool for consistency.

Files:

• pkg/parser/schemas/main_workflow_schema.json (has $comment)
• pkg/parser/schemas/included_file_schema.json (missing $comment)

---

3. Engine Default Value Missing in Included Schema (PERSISTENT)

Issue: The engine field has different default value specifications across schemas.

Evidence:

• main_workflow_schema.json: properties.engine.default = "copilot"
• included_file_schema.json: No default field specified

Impact:

• Inconsistent schema metadata
• IDE autocomplete may not suggest default value for included files
• Schema consumers cannot infer default behavior

Recommendation: Add "default": "copilot" to included_file_schema.json properties.engine OR document why included files should not have a default engine.

Files:

• pkg/parser/schemas/main_workflow_schema.json:38 (has default)
• pkg/parser/schemas/included_file_schema.json (no default)

---

4. Safe-Outputs Scope Restriction (INTENTIONAL, VERIFIED)

Issue: The safe-outputs field has dramatically different scope between main and included schemas.

Evidence:

• main_workflow_schema.json: 38 safe-output operation types (issues, discussions, comments, labels, pull-requests, agent-tasks, etc.)
• included_file_schema.json: Only 1 operation type (jobs)
• included schema description: "Safe outputs configuration (only jobs allowed in included files)"

Analysis: This appears to be an intentional design decision. The description explicitly states the restriction. Included files can only define job outputs, while main workflows can define all output types.

Impact:

• Limits included file capabilities by design
• May prevent code reuse for safe-output definitions
• Undocumented in reference documentation (only in schema description)

Recommendation: Document this restriction in docs/src/content/docs/reference/ to explain why included files have limited safe-outputs scope.

---

5. Tools Scope Restriction (INTENTIONAL, VERIFIED)

Issue: The tools field supports different tool sets between main and included schemas.

Evidence:

• main_workflow_schema.json: 13 tools (agentic-workflows, bash, cache-memory, edit, github, playwright, repo-memory, safety-prompt, serena, startup-timeout, timeout, web-fetch, web-search)
• included_file_schema.json: 7 tools (agentic-workflows, bash, cache-memory, github, playwright, repo-memory, serena)
• Missing in included: edit, safety-prompt, startup-timeout, timeout, web-fetch, web-search

Analysis: This restriction appears intentional but is undocumented. The missing tools are meta-configuration fields (safety-prompt, timeouts) and advanced features (edit, web-fetch, web-search).

Impact:

• Limits included file tool configuration capabilities
• May prevent sharing advanced tool configurations
• Not documented in reference materials

Recommendation: Document this restriction in docs/src/content/docs/reference/ to explain which tools are available in included files vs main workflows and why.

---

Positive Findings

Schema Quality Improvements

1. Top-level metadata NOW PRESENT: All three schemas now have proper $id, title, and description fields (fixed from previous runs)
2. http_mcp_tool consistency: Definitions are byte-for-byte identical across main and included schemas
3. No broken references: All $ref references are valid, all $defs are used
4. Permissions structure identical: Both main and included schemas support the same permissions patterns (string shortcuts + object notation)

Schema Structure Excellence

• DRY discipline: MCP tool definitions properly reused via $defs
• No dead definitions: Every $def is actively referenced
• Proper schema versioning: All schemas use JSON Schema Draft 07

---

Recommendations

High Priority

1. Fix MCP version type: Update mcp_config_schema.json to accept ["string", "number"] to match implementation
2. Add $comment to included schema: Copy stdio_mcp_tool validation documentation from main schema

Medium Priority

3. Clarify engine default: Either add default to included schema or document why it's intentionally omitted
4. Document scope restrictions: Add documentation explaining why safe-outputs and tools have limited scope in included files

---

Strategy Performance

Strategy: Cross-Schema Consistency & Type Analysis
Success Count: 11 (including this run)
Findings This Run: 5 (1 critical, 4 moderate)
New Issues: 0
Persistent Issues: 3 (MCP version, $comment, engine default)
Effectiveness: Very High
Should Reuse: Yes (every 4-5 analyses)

Key Insight: This strategy excels at finding inter-schema drift and type inconsistencies. All 5 findings are persistent issues that have survived multiple analysis runs, indicating they may be deferred technical debt or intentional design decisions that need documentation.

---

Next Steps

• Update mcp_config_schema.json version field to accept string|number
• Add $comment field to included_file_schema.json stdio_mcp_tool definition
• Document engine default value policy for included files
• Document safe-outputs scope restriction in reference docs
• Document tools scope restriction in reference docs

References:

• §20684597868

AI generated by Schema Consistency Checker

[pelikhan]

/plan

[github-actions[bot]]

🎉 Yo ho ho! Plan Command found the treasure and completed successfully! ⚓💰