[Schema Consistency] 🔍 Schema Consistency Check - Cross-Schema Analysis (2025-10-25)

[github-actions[bot]]

🔍 Schema Consistency Check - 2025-10-25

Summary

• Inconsistencies Found: 5 Critical/High Priority Issues
• Categories Analyzed: Cross-schema consistency (main_workflow_schema.json, included_file_schema.json, mcp_config_schema.json)
• Strategy Used: Cross-Schema Consistency & Type Analysis (NEW)
• New Strategy: ✅ YES - This strategy compares schemas against each other, unlike previous strategies that compared schema vs code vs docs

Critical Issues

1. ⚠️ Container Pattern Mismatch Between Schemas

Severity: CRITICAL

Issue: The container field has DIFFERENT regex patterns across schemas:

• mcp_config_schema.json: ^[a-zA-Z0-9][a-zA-Z0-9/_.-]*$ ❌ (NO colon)
• included_file_schema.json: ^[a-zA-Z0-9][a-zA-Z0-9/:_.-]*$ ✅ (colon allowed)
• main_workflow_schema.json: ^[a-zA-Z0-9][a-zA-Z0-9/:_.-]*$ ✅ (colon allowed)

Impact: mcp_config_schema.json would REJECT valid container images like registry:5000/myimage while other schemas accept them.

Location:

• pkg/parser/schemas/mcp_config_schema.json:24
• pkg/parser/schemas/included_file_schema.json:325

Fix: Add : to the character class in mcp_config_schema.json to match the other two schemas.

---

2. ⚠️ Missing entrypointArgs in included_file_schema.json

Severity: CRITICAL

Issue: The entrypointArgs field is:

• ✅ Defined in mcp_config_schema.json (lines 34-40)
• ✅ Parsed by pkg/parser/mcp.go:74
• ✅ Compiled by pkg/workflow/mcp-config.go:796-859
• ✅ Documented in docs/src/content/docs/guides/mcps.md
• ✅ Has test coverage in pkg/workflow/mcp_container_args_test.go
• ❌ MISSING from included_file_schema.json stdio_mcp_tool definition

Impact: Included files using MCP servers cannot use entrypointArgs according to schema validation, even though the parser and compiler fully support it.

Also Missing: headers and url fields

Fix: Add entrypointArgs, headers, and url fields to the stdio_mcp_tool definition in included_file_schema.json to match mcp_config_schema.json.

---

3. ⚠️ Bash Tool Type Inconsistency

Severity: HIGH

Issue: The bash tool accepts different types in different schemas:

• main_workflow_schema.json: null | boolean | array
  • ✅ Allows bash: true and bash: false
• included_file_schema.json: null | array only
  • ❌ Does NOT allow boolean type

Impact:

• If an included file specifies bash: true, it would fail schema validation
• Documentation shows bash: true as valid in examples
• Inconsistent developer experience

Fix: Add boolean type to included_file_schema.json bash tool definition.

---

Schema Improvements Needed

4. Missing safe_job Definition in main_workflow_schema.json

Severity: MEDIUM

Issue: safe_job is defined in included_file_schema.json $defs but NOT in main_workflow_schema.json $defs.

Current $defs comparison:

main_workflow_schema.json:
  - engine_config
  - http_mcp_tool
  - stdio_mcp_tool

included_file_schema.json:
  - http_mcp_tool
  - safe_job         ← Only here!
  - stdio_mcp_tool

Impact: Main workflow files cannot properly validate safe-outputs job definitions.

Fix: Add safe_job to main_workflow_schema.json $defs or use $ref to reference it from included_file_schema.json.

---

5. MCP Tool Definition Duplication

Severity: MEDIUM (Architectural)

Issue: The stdio_mcp_tool and http_mcp_tool definitions are DUPLICATED across schemas with slight variations, causing them to drift apart (as seen in issues #1, #2, and #3 above).

Impact:

• Maintenance burden - changes must be replicated
• High risk of inconsistencies
• Already caused 3 critical bugs

Recommendation:

1. Create a shared MCP schema file (mcp_definitions_schema.json)
2. Use $ref to reference from all three schemas
3. Single source of truth for MCP configuration

---

Documentation Gaps

Well Documented ✅

• entrypointArgs - Good examples in guides/mcps.md
• MCP container usage patterns
• Bash tool boolean usage shown in examples

Needs Documentation ⚠️

• Schema differences between main and included files
• Why bash boolean type is not available in included files (if intentional)
• Container pattern requirements (colon support for registry ports)
• Which fields are available in which schema contexts

---

Positive Findings ✅

Consistent Definitions (Good!)

1. cache-memory tool types: Identical across both main and included schemas

   • Both support: boolean | null | object | array

2. Network configuration: Consistent structure in MCP definitions across all schemas

3. Environment variable patterns: Same regex everywhere

   • ^[A-Z_][A-Z0-9_]*$ enforces uppercase with underscores

4. Type handling in parser: No problematic type coercion found

   • Parser properly handles []any to []string conversions
   • Safe type assertions with checks

---

Recommendations

Immediate (Critical) 🔴

1. Fix container pattern in pkg/parser/schemas/mcp_config_schema.json

   • Change: ^[a-zA-Z0-9][a-zA-Z0-9/_.-]*$
   • To: ^[a-zA-Z0-9][a-zA-Z0-9/:_.-]*$

2. Add entrypointArgs to pkg/parser/schemas/included_file_schema.json

   • Add to stdio_mcp_tool properties
   • Also add: headers, url for completeness

High Priority 🟡

3. Add boolean type to included_file_schema.json tools.bash definition

   • Match main_workflow_schema.json behavior
   • Update description if needed

4. Add safe_job to main_workflow_schema.json $defs

   • Either duplicate or use $ref
   • Enables proper validation in main workflows

Medium Priority 🟢

5. Refactor to shared schema file

   • Create pkg/parser/schemas/shared/mcp_definitions.json
   • Use $ref from all three schemas
   • Prevents future drift

6. Document schema context differences

   • Create docs page explaining main vs included vs mcp schemas
   • Document which fields are available where

---

Strategy Performance

• Strategy Used: Cross-Schema Consistency & Type Analysis (NEW)
• Findings: 5 critical/high priority issues
• Effectiveness: VERY HIGH
• Should Reuse: ✅ YES

Why This Strategy Is Effective:

• Previous strategies (001-003) compared: schema ↔ code ↔ docs ↔ workflows
• This strategy compares: schema ↔ schema ↔ schema
• Found a completely different class of issues (internal schema inconsistencies)
• Revealed architectural problems (duplication, no shared source of truth)

Recommendation: Run this strategy every 3-4 analyses to catch schema drift before it causes runtime issues.

---

Next Steps

• Fix container pattern regex in mcp_config_schema.json
• Add missing fields (entrypointArgs, headers, url) to included_file_schema.json
• Add boolean type to bash tool in included_file_schema.json
• Add safe_job definition to main_workflow_schema.json
• Consider creating shared MCP definitions schema
• Document schema context differences

---

Files Analyzed

Schemas (3 files, 3940 total lines)

• pkg/parser/schemas/main_workflow_schema.json (3159 lines)
• pkg/parser/schemas/included_file_schema.json (583 lines)
• pkg/parser/schemas/mcp_config_schema.json (198 lines)

Implementation

• pkg/parser/mcp.go
• pkg/parser/frontmatter.go
• pkg/workflow/mcp-config.go
• pkg/workflow/mcp_container_args_test.go

Documentation

• docs/src/content/docs/guides/mcps.md
• docs/src/content/docs/reference/frontmatter-full.md
• docs/src/content/docs/reference/tools.md

---

Analysis Date: 2025-10-25
Strategy: Cross-Schema Consistency & Type Analysis
Cache Updated: /tmp/gh-aw/cache-memory/strategies.json
Detailed Findings: /tmp/gh-aw/cache-memory/findings_2025-10-25.md

AI generated by Schema Consistency Checker

[pelikhan]

/plan point 1, 2, 3. Ignore other recommendations

[pelikhan]

/plan create issues for 1, 2, 3

[github-actions[bot]]

Agentic Plan Command triggered by this discussion comment.

[pelikhan]

/plan generate item 1,2,3

[github-actions[bot]]

Agentic Plan Command triggered by this discussion comment.

[pelikhan]

/plan generate issue for item 1,2,3

[github-actions[bot]]

Agentic Plan Command triggered by this discussion comment.

[github-actions[bot]]

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