[Schema Consistency] 🔍 Schema Consistency Analysis - 8 Inconsistencies Found (2025-10-23)

[github-actions[bot]]

🔍 Schema Consistency Check - 2025-10-23

Summary

• Inconsistencies Found: 8 significant issues
• Categories Analyzed: Schema, Parser, Documentation, Workflows
• Strategy Used: Field Enumeration and Type Analysis (Comprehensive)
• Analysis Date: October 23, 2025

---

🚨 Critical Issues

1. Missing defaults Field Implementation ⚠️ HIGH PRIORITY

Issue: The defaults field is defined in the JSON schema but NOT implemented in the workflow compiler.

• Schema: pkg/parser/schemas/main_workflow_schema.json - defines defaults with properties for run.shell and run.working-directory
• Parser: pkg/workflow/compiler.go - WorkflowData struct does NOT have a Defaults field
• Impact: Users can define defaults: in frontmatter (schema validation passes) but it will be silently ignored during compilation
• Evidence:
  • Schema location: pkg/parser/schemas/main_workflow_schema.json:properties.defaults
  • No extraction in compiler: grep -n "extractTopLevelYAMLSection.*defaults" pkg/workflow/*.go returns nothing
  • Workflow using it: .github/workflows/github-mcp-tools-report.md may attempt to use this field
• Recommendation: Either implement defaults field extraction and rendering, or remove from schema with deprecation notice

2. Undocumented githubActionsStep Schema Field ⚠️ MEDIUM PRIORITY

Issue: The githubActionsStep field exists in schema but appears to be unused and undocumented.

• Schema: Defines a complete GitHub Actions step object with name, id, if, uses, run, etc.
• Parser: No evidence of extraction or usage in pkg/workflow/*.go
• Documentation: Not mentioned in any docs
• Workflows: No workflows use this field
• Impact: Schema pollution - may confuse users or schema validators
• Recommendation: Remove from schema if truly unused, or document its purpose

3. Bash Tool Schema Type Mismatch ⚠️ LOW-MEDIUM PRIORITY

Issue: Schema defines bash as null | array, but workflows commonly use bash: true (boolean).

• Schema: pkg/parser/schemas/main_workflow_schema.json - only allows null or array of strings
• Parser: pkg/workflow/tools_types.go:221 - parseBashTool() handles nil and arrays, but not boolean
• Actual Usage: Multiple workflows use bash: true pattern
• Impact: Schema validation would reject valid common usage pattern
• Recommendation: Update schema to include boolean type in oneOf for bash tool

---

📚 Documentation Gaps

4. Missing Main Frontmatter.md Entries

The following schema fields are missing from docs/src/content/docs/reference/frontmatter.md (though some are documented elsewhere):

Completely Undocumented:

• defaults - Standard GitHub Actions field for default shell/working-directory
• githubActionsStep - Purpose unclear (may be internal)
• name - Standard GitHub Actions workflow name (assumed known?)
• steps - Custom workflow steps (mentioned but not detailed in frontmatter.md)
• jobs - Multi-job workflow support (mentioned but not detailed)
• cache - Top-level cache configuration

Documented in Separate Files (but should be referenced in main frontmatter.md):

• tools → documented in tools.md ✓ (referenced)
• imports → documented in imports.md ✓ (referenced)
• cache-memory → documented in cache-memory.md ✓ (referenced)
• command → documented in command-triggers.md ✓ (referenced)
• mcp-servers → mentioned in tools.md but needs more detail
• runtimes → mentioned in frontmatter-full.md but not in main frontmatter.md
• post-steps → used in workflows but only in frontmatter-full.md

Note: frontmatter-full.md has comprehensive coverage (28 fields documented)

5. Bash Tool Boolean Support 🔧 HIGH PRIORITY

Current Schema:

"bash": {
  "oneOf": [
    {"type": "null"},
    {"type": "array", "items": {"type": "string"}}
  ]
}

Should Be:

"bash": {
  "oneOf": [
    {"type": "null"},
    {"type": "boolean"},
    {"type": "array", "items": {"type": "string"}}
  ]
}

Justification: Common usage pattern in workflows is bash: true

6. MCP-Servers Documentation Gap 📚 MEDIUM PRIORITY

Issue: mcp-servers field is in schema and used in workflows, but only briefly mentioned in tools.md.

• Schema: Well-defined with stdio/http MCP server types
• Usage: Used in 0 workflows in this analysis (all use imports instead)
• Docs: Brief mention in tools.md and imports.md
• Recommendation: Add dedicated section in tools.md or create separate mcp-servers.md guide

7. Runtimes Field Documentation Gap 📚 MEDIUM PRIORITY

Issue: runtimes field documented only in frontmatter-full.md, not in main frontmatter.md.

• Schema: Well-defined for runtime version overrides (node, python, etc.)
• Parser: Fully implemented in pkg/workflow/runtime_setup.go
• Usage: Not found in current workflows (feature may be new or rarely used)
• Documentation: Only in auto-generated frontmatter-full.md
• Recommendation: Add section to main frontmatter.md about runtime overrides

8. Post-Steps Documentation Gap 📚 MEDIUM PRIORITY

Issue: post-steps field is implemented and used but only in frontmatter-full.md.

• Schema: Defined as array of GitHub Actions steps
• Parser: Fully implemented in pkg/workflow/compiler.go:903,3138
• Usage: .github/workflows/test-post-steps.md uses this feature
• Documentation: Only in frontmatter-full.md
• Tests: Has dedicated tests in compiler_test.go
• Recommendation: Add section to main frontmatter.md about post-execution steps

---

🔧 Recommendations

Immediate Actions (High Priority)

1. Fix defaults field inconsistency - Either:

   • Implement extraction and rendering in compiler
   • OR remove from schema with deprecation notice

2. Update bash tool schema - Add boolean type to match actual usage

3. Audit githubActionsStep field - Determine if it's needed and document or remove

Medium Priority

4. Enhance main frontmatter.md - Add sections or references for:

   • runtimes - runtime version overrides
   • post-steps - post-execution steps
   • mcp-servers - cross-reference to tools.md
   • jobs - multi-job workflow support
   • cache - top-level cache config

5. Cross-reference section - Add "See Also" section at end of frontmatter.md linking to:

   • tools.md, imports.md, cache-memory.md, command-triggers.md, etc.

Low Priority

6. Schema documentation comments - Ensure all schema fields have clear descriptions
7. Example workflows - Create examples for rarely-used features (runtimes, post-steps, defaults)

---

📊 Analysis Methodology

This analysis used a comprehensive field enumeration strategy:

1. Schema Field Extraction: Used jq to extract all top-level property names from JSON schema
2. Documentation Parsing: Extracted H3 headers from frontmatter.md as documented fields
3. Diff Analysis: Compared schema fields vs documented fields to find gaps
4. Parser Code Review: Searched for field extraction and handling in compiler code
5. Workflow Pattern Analysis: Searched actual workflows for field usage patterns
6. Type Validation: Compared schema types vs parser implementation vs actual usage

This multi-dimensional approach ensures consistency across all four areas:

• Schema ↔ Parser
• Schema ↔ Documentation
• Parser ↔ Documentation
• All three ↔ Actual Workflow Usage

---

📁 Files Analyzed

Schema Files:

• pkg/parser/schemas/main_workflow_schema.json (26,676 tokens - analyzed via jq)

Parser/Compiler Files:

• pkg/parser/frontmatter.go
• pkg/workflow/compiler.go
• pkg/workflow/tools.go
• pkg/workflow/tools_types.go
• pkg/workflow/runtime_setup.go
• pkg/workflow/*.go (multiple files)

Documentation Files:

• docs/src/content/docs/reference/frontmatter.md
• docs/src/content/docs/reference/frontmatter-full.md
• docs/src/content/docs/reference/tools.md
• docs/src/content/docs/reference/imports.md
• docs/src/content/docs/reference/cache-memory.md

Workflow Files:

• .github/workflows/audit-workflows.md
• .github/workflows/brave.md
• .github/workflows/test-post-steps.md
• .github/workflows/github-mcp-tools-report.md
• Multiple other workflow files (30+ analyzed)

---

🤖 Generated by Schema Consistency Checker Agent
📅 Analysis Date: 2025-10-23
🔄 Strategy: Comprehensive Field Enumeration and Type Analysis

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 month ago.