[Schema Consistency] Schema Consistency Analysis - 2026-01-21: Critical Documentation Gap & Missing Field

[github-actions[bot]]

Analysis of schema consistency across the main workflow schema, MCP config schema, parser implementation, compiler code, and documentation.

Summary

• Inconsistencies Found: 5 (2 critical, 1 moderate, 2 documentation)
• Categories Analyzed: Schema files, Parser implementation, Compiler code, Documentation
• Strategy Used: Strategy-004 (Cross-Schema Consistency & Type Analysis)
• New Critical Discovery: Schema file architecture changed but documentation not updated

Critical Issues

🔴 Issue #1: Schema File Removed, Documentation Outdated

Problem: The included_file_schema.json file was removed from the codebase, but multiple documentation files still reference it.

Status:

• ❌ File exists: pkg/parser/schemas/included_file_schema.json - NO (removed)
• ✅ Code updated: No references in pkg/parser/*.go
• ❌ Documentation updated: NO (still references old file)

Current Architecture (2 schemas):

• main_workflow_schema.json - Used for BOTH main workflows AND included/shared workflows
• mcp_config_schema.json - Used for MCP tool configurations

Files Requiring Updates:

• specs/schema-validation.md:15, 91 - Remove included_file_schema references
• skills/developer/SKILL.md:1094 - Update schema files table
• .github/workflows/schema-consistency-checker.md:85 - Remove from key files list
• .github/workflows/schema-consistency-checker.lock.yml:690 - Update workflow instructions

Impact: Documentation misleads developers and users about the schema architecture.

Recommendation: Update all documentation to reflect the current two-schema architecture.

---

🔴 Issue #2: safe-jobs Field Missing from Schema

Problem: The safe-jobs top-level field is accessed in compiler code but NOT defined in main_workflow_schema.json.

Evidence:

• Used in Code:
  • pkg/workflow/safe_jobs.go:40 - frontmatter["safe-jobs"]
  • pkg/workflow/compiler_orchestrator.go:744 - extractSafeJobsFromFrontmatter()
  • pkg/workflow/compiler_safe_output_jobs.go:55-60 - buildSafeJobs()
• Schema Status: NOT in main_workflow_schema.json (0 of 38 top-level properties)
• Code Comment (safe_jobs.go:38):

  "User workflows should use 'safe-outputs.jobs' syntax; the top-level 'safe-jobs' key is NOT supported."

Analysis: safe-jobs appears to be an internal implementation detail that users shouldn't use directly. Users should use safe-outputs.jobs instead.

Impact:

• Schema validation cannot catch invalid safe-jobs configurations
• No type checking or structure enforcement
• Potential for malformed data causing runtime errors

Recommendation: Choose one approach:

1. Add safe-jobs to schema with proper validation (if it's valid user-facing)
2. Document it as internal-only; users must use safe-outputs.jobs
3. Remove frontmatter["safe-jobs"] access if truly not user-facing

---

Moderate Findings

⚠️ Issue #3: 18 Schema Properties Not Directly Accessed

Problem: 18 properties defined in schema are NOT accessed via frontmatter["key"] in compiler.

View Properties Not Accessed

Properties in schema but not accessed in pkg/workflow/*.go:

• cache
• command
• concurrency
• container
• env
• environment
• imports
• labels
• metadata
• post-steps
• run-name
• runs-on
• runtimes
• services
• steps
• strict
• timeout-minutes
• timeout_minutes

Analysis:

• Many of these (cache, concurrency, container, env, runs-on, steps) are standard GitHub Actions fields that may be passed through directly to generated YAML without compiler processing
• Others (imports, metadata, runtimes) might be processed indirectly
• Need verification if these are intentional passthrough fields or unused

Impact: LOW if passthrough is intentional, MEDIUM if some should be removed.

Recommendation: Document which fields are "GitHub Actions passthrough" vs "compiler-processed".

---

Documentation Issues

📝 Issue #4: safe-jobs Mentioned But Not Documented

Problem: safe-jobs mentioned in compilation-process.md but not in frontmatter reference.

Evidence:

• ✅ Mentioned: docs/src/content/docs/reference/compilation-process.md:270 - "use safe-jobs for custom logic"
• ❌ Not documented: docs/src/content/docs/reference/frontmatter.md - No mentions

Recommendation: If user-facing, document it properly. If internal-only, remove the reference.

---

Positive Findings

✅ Schema Consolidation Complete in Code: Parser and compiler successfully updated to use only 2 schemas with no remaining included_file_schema references. Clean migration!

✅ Comprehensive MCP Validation: MCP config schema properly integrated with dedicated ValidateMCPConfigWithSchema() function and clear error messages.

---

Recommendations

🔥 High Priority:

1. Update Documentation - Remove all included_file_schema.json references from:

   • specs/schema-validation.md
   • skills/developer/SKILL.md
   • .github/workflows/schema-consistency-checker.md
   • .github/workflows/schema-consistency-checker.lock.yml

2. Clarify safe-jobs - Either:

   • Add to schema with validation
   • Document as internal-only
   • Remove from frontmatter access

3. Document safe-jobs vs safe-outputs.jobs - Clear usage guidance

⚡ Medium Priority:

4. Document Passthrough Fields - Clearly identify which schema fields are GitHub Actions passthroughs vs compiler-processed

5. Verify "Unused" Properties - Confirm all 18 properties are intentionally passthrough or should be removed

📋 Low Priority:

6. Update compilation-process.md - Align with current architecture

---

Schema Architecture Evolution

Previous (3 schemas):

• main_workflow_schema.json
• included_file_schema.json ← REMOVED
• mcp_config_schema.json

Current (2 schemas):

• main_workflow_schema.json (used for both main AND included workflows)
• mcp_config_schema.json

Key Insight: Code migration completed cleanly, but documentation lagged behind. This is a classic refactoring debt pattern.

---

Strategy Performance

• Strategy: Strategy-004 (Cross-Schema Consistency & Type Analysis)
• Effectiveness: VERY HIGH ⭐⭐⭐⭐⭐
• Success Count: 15 total runs
• Findings This Run: 2 critical, 1 moderate, 2 documentation
• Should Reuse: ✅ YES - Excellent for catching schema drift and doc gaps

Why This Strategy Works:

• Compares schema definitions against actual code usage
• Catches when code evolves but schema/docs don't
• Finds fields used in code but missing from schema
• Identifies architectural changes that affect documentation

---

Files Analyzed

Schemas (2 files):

• ✅ pkg/parser/schemas/main_workflow_schema.json (287,994 bytes, 38 top-level properties)
• ✅ pkg/parser/schemas/mcp_config_schema.json (7,905 bytes, 14 top-level properties)

Parser (63 Go files, 24,315 lines):

• ✅ pkg/parser/*.go - Frontmatter parsing, schema validation, import processing

Compiler (239 Go files):

• ✅ pkg/workflow/*.go - Workflow compilation, safe-outputs, jobs generation

Documentation:

• ✅ docs/src/content/docs/reference/ - Frontmatter reference, compilation docs
• ✅ specs/schema-validation.md - Schema architecture specs
• ✅ .github/workflows/schema-consistency-checker.md - This workflow's instructions

---

🔎 Next Steps: Address the critical documentation gaps to prevent developer confusion and ensure accurate reference materials.

References:

• §21230068644

AI generated by Schema Consistency Checker

• expires on Jan 28, 2026, 11:56 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-01-28T23:56:01.684Z.