[Schema Consistency] 🔍 Schema Consistency Check - November 1, 2025: Cross-Schema Drift Analysis

[github-actions[bot]]

🔍 Schema Consistency Check - November 1, 2025

Analysis of the three JSON schemas revealed 6 critical inconsistencies in schema definitions, primarily schema drift between main_workflow_schema.json and included_file_schema.json. These inconsistencies could lead to validation errors or feature unavailability.

**Key (redacted) The main schema's MCP tool definition is missing critical fields (headers, url) that exist in both the included schema and the actual code implementation.

Full Report Details

Analysis Metadata

• Strategy: Strategy-004 (Cross-Schema Consistency & Type Analysis)
• Focus: Internal schema consistency across all three schemas
• Schemas Analyzed: main_workflow_schema.json (126KB), included_file_schema.json (22KB), mcp_config_schema.json (4KB)
• Findings: 6 inconsistencies (4 schema drift, 1 architectural, 1 feature disparity)
• Severity Breakdown: 1 HIGH, 3 MEDIUM, 2 LOW

---

Critical Issues

1. 🔴 HIGH: MCP stdio_mcp_tool Missing HTTP Fields

**(redacted)
The main workflow schema's $defs.stdio_mcp_tool definition is missing two critical fields that exist in the included schema and are used by the code implementation:

• headers (map[string]string for HTTP headers)
• url (string for HTTP MCP connections)

**(redacted)

Code implementation expects these fields:

// pkg/parser/mcp.(redacted)
URL            string            `json:"url"`            // for http
Headers        map[string]string `json:"headers"`        // for http

Schema comparison:

# Main schema stdio_mcp_tool properties:
"allowed", "args", "command", "container", "entrypointArgs", 
"env", "network", "registry", "type", "version"

# Included schema stdio_mcp_tool properties (correct):
"allowed", "args", "command", "container", "entrypointArgs", 
"env", "headers", "network", "registry", "type", "url", "version"

**(redacted)

• Users defining stdio MCP tools in main workflows cannot specify HTTP headers or URLs
• Schema validation will reject valid configurations
• Feature parity broken between main and included files
• Documentation may reference fields that aren't validated

**(redacted)
Add headers and url properties to main_workflow_schema.json at $defs.stdio_mcp_tool.properties

---

2. 🟡 MEDIUM: Engine Enum Missing 'copilot'

**(redacted)
The included file schema is missing copilot from the engine enum values, preventing use of GitHub Copilot in included workflow files.

**(redacted)

// main_workflow_schema.json - CORRECT
{
  "enum": ["claude", "codex", "copilot", "custom"]
}

// included_file_schema.json - MISSING COPILOT
{
  "enum": ["claude", "codex", "custom"]
}

This affects two locations in included_file_schema.json:

1. properties.engine.oneOf[0].enum (string variant)
2. properties.engine.oneOf[1].properties.id.enum (object variant)

**(redacted)

• Cannot specify engine: copilot in included workflow files
• Users get validation errors for valid configuration
• Inconsistent feature availability

**(redacted)
Add "copilot" to both engine enum locations in included_file_schema.json

---

3. 🟡 MEDIUM: Safe-Outputs Severe Feature Disparity

**(redacted)
The included file schema only has 1 of 20 safe-outputs properties available.

**Available in Included (redacted)

• jobs

Missing from Included Schema (19 properties):

• add-comment
• add-labels
• allowed-domains
• create-agent-task
• create-code-scanning-alert
• create-discussion
• create-issue
• create-pull-request
• create-pull-request-review-comment
• env
• github-token
• max-patch-size
• missing-tool
• push-to-pull-request-branch
• runs-on
• staged
• threat-detection
• update-issue
• upload-assets

**(redacted)

• Severely limited safe-outputs functionality in included files
• This may be intentional design (security boundary?) OR schema drift

**(redacted)

• If intentional: Document in included_file_schema.json description why safe-outputs is limited
• If unintentional: Add missing properties to achieve feature parity
• Action needed: Determine design intent and document accordingly

---

4. 🟡 MEDIUM: Tools Field Disparity

**(redacted)
The included schema defines only 3 tools while the main schema defines 11.

**Available in Included (redacted)

• bash
• cache-memory
• github

**Missing from Included (redacted)

• agentic-workflows
• edit
• playwright
• safety-prompt
• startup-timeout
• timeout
• web-fetch
• web-search

**(redacted)

• Reduced tool access in included files
• May be security feature or schema drift

**(redacted)

• Document which tools are intentionally available/restricted in included files
• Clarify if this is a security boundary or oversight

---

5. 🔵 LOW: Schema $defs Duplication Anti-Pattern

**(redacted)
MCP tool definitions are duplicated across schemas with no shared $ref, leading to drift (as evidenced by Finding #1).

**Current (redacted)

main_workflow_schema.json
  $defs:
    - stdio_mcp_tool (version A - incomplete)
    - http_mcp_tool
    - engine_config
    - github_token

included_file_schema.json
  $defs:
    - stdio_mcp_tool (version B - complete)
    - http_mcp_tool
    - safe_job

mcp_config_schema.json
  - Flat structure (no $defs)

**(redacted)

• Schema drift when updating one but not others
• Maintenance burden
• Inconsistency risk (already occurred)

**(redacted)
Consider schema refactoring:

schemas/
  common/
    mcp_tools_defs.json  # Shared MCP definitions
  main_workflow_schema.json  # $ref to common
  included_file_schema.json  # $ref to common
  mcp_config_schema.json     # $ref to common

---

6. 🔵 LOW: Permissions Definition Complexity

**(redacted)
Both schemas define the same 16 permission scopes but with different structural approaches.

**(redacted)

• Main schema: 16 scopes including all, attestations, models
• Included schema: Same 16 scopes, slightly different structure
• Both functionally equivalent

**(redacted)

• Minimal validation impact
• Code maintenance complexity

**(redacted)

• Consider using $ref to share permission definitions
• Low priority fix

---

Positive Findings ✅

1. Runtimes Consistency: Perfect consistency across main and included schemas
2. Network Field: Consistent definitions (included has simplified version)
3. Bash Tool Types: Consistent type handling (null|boolean|array)
4. Schema Quality: Well-structured with comprehensive descriptions
5. No Type Coercion Issues: Types match between schemas where they overlap

---

Recommendations Summary

Immediate Actions (HIGH Priority)

1. Fix stdio_mcp_tool in main_workflow_schema.json: Add headers and url properties
2. Add copilot to included_file_schema.json: Update both engine enum locations

Short-term Actions (MEDIUM Priority)

3. Document safe-outputs design intent: Clarify if limited access is intentional
4. Document tools availability: Specify which tools work in included files
5. Review feature parity: Determine if disparities are bugs or features

Long-term Actions (LOW Priority)

6. Refactor schemas: Create shared definitions to prevent drift
7. Establish schema governance: Process for keeping schemas in sync
8. Add schema tests: Automated tests to catch drift

---

Files Analyzed

• pkg/parser/schemas/main_workflow_schema.json (126,015 bytes, 612 objects)
• pkg/parser/schemas/included_file_schema.json (22,597 bytes, 110 objects)
• pkg/parser/schemas/mcp_config_schema.json (4,434 bytes, 30 objects)
• pkg/parser/mcp.go (implementation validation)

---

Strategy Performance

• Strategy Used: Strategy-004 (Cross-Schema Consistency & Type Analysis)
• Last Used: 2025-10-25 (7 days ago)
• Success Count: 2 (now 3)
• Findings This Run: 6 inconsistencies
• Effectiveness: Very High
• Should Reuse: Yes - excellent for catching schema evolution drift
• Complements: Strategies 001, 002, 003 (which focus on schema-vs-code consistency)

**Why This Strategy is (redacted)
Previous strategies compare schema against code or documentation. This strategy compares schemas against each other, revealing internal inconsistencies invisible to other approaches.

---

Next Analysis Recommendation

Suggested Next Strategy: Strategy-002 (Enhanced Enum Validation) or Strategy-005 (Conditional Logic Analysis)

Reasoning: After fixing schema-to-schema issues, validate that enums and conditionals are correctly implemented in code.

---

**(redacted)

• Workflow Run §18990006046

AI generated by Schema Consistency Checker

[github-actions[bot]]

This discussion was automatically closed because it was created by an agentic workflow more than 1 week ago.