[Schema Consistency] Cross-Schema Consistency Analysis - 2026-01-31

[github-actions[bot]]

Summary

Analyzed consistency between main workflow schema and MCP configuration schema using Strategy-004 (Cross-Schema Consistency & Type Analysis).

• Inconsistencies Found: 3
• Categories Analyzed: Schema definitions, Parser implementation, Documentation, Workflow usage
• Strategy Used: Cross-Schema Consistency & Type Analysis
• Overall Assessment: ✅ Excellent - Schemas are highly consistent with only minor documentation gaps

Key Metrics

• Critical Issues: 0
• Moderate Issues: 1
• Minor Issues: 2
• Positive Findings: 8

---

Critical Issues

None found. All MCP fields are properly defined, implemented, and functional.

---

Moderate Issues

1. Documentation Completeness Gap - Examples Missing

Issue: The main schema's stdio_mcp_tool.properties.env field lacks examples, while the MCP config schema includes comprehensive examples.

Location: pkg/parser/schemas/main_workflow_schema.json

Current State

Main schema (stdio_mcp_tool.properties.env):

{
  "type": "object",
  "patternProperties": {
    "^[A-Z_][A-Z0-9_]*$": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "description": "Environment variables for MCP server"
}

MCP config schema (properties.env):

{
  "type": "object",
  "patternProperties": {
    "^[A-Z_][A-Z0-9_]*$": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "description": "Environment variables for MCP server",
  "examples": [
    {"GITHUB_TOKEN": "${{ secrets.GITHUB_TOKEN }}"},
    {"API_KEY": "${{ secrets.CUSTOM_API_KEY }}", "LOG_LEVEL": "debug"},
    {"BRAVE_API_KEY": "${{ secrets.BRAVE_API_KEY }}"}
  ]
}
```

</details>

**Impact**: Medium - IDE autocomplete and schema validation tools have reduced discoverability for the `env` field in the main schema.

**Recommendation**: Add the same examples array to the main schema's `env` field definition.

---

## Minor Issues

### 2. Description Wording Variation - Mounts Field

**Issue**: The `mounts` field has slightly different description wording between schemas.

**Locations**:
- Main schema: `pkg/parser/schemas/main_workflow_schema.json` - `$defs.stdio_mcp_tool.properties.mounts`
- MCP config schema: `pkg/parser/schemas/mcp_config_schema.json` - `properties.mounts`

<details>
<summary><b>Wording Comparison</b></summary>

**Main schema**:
```
"Volume mounts for container in format 'source:dest:mode' where mode is 'ro' or 'rw'"
```

**MCP config schema**:
```
"Volume mounts for container (format: 'source:dest:mode' where mode is 'ro' or 'rw')"

Impact: Low - Purely cosmetic. Both descriptions are clear and accurate.

Recommendation: Standardize on one wording format (suggest the MCP config schema version with parentheses).

3. Schema Metadata Inconsistency - Version Field

Issue: The MCP config schema includes a version field in its metadata, but the main schema does not.

Metadata Comparison

Main schema metadata:

{
  "$schema": "(jsonschema.org/redacted)
  "$id": "https://github.com/githubnext/gh-aw/schemas/main_workflow_schema.json",
  "title": "GitHub Agentic Workflow Schema",
  "description": "JSON Schema for validating agentic workflow frontmatter configuration"
}

MCP config schema metadata:

{
  "$schema": "(jsonschema.org/redacted)
  "$id": "https://github.com/githubnext/gh-aw/schemas/mcp_config_schema.json",
  "title": "MCP Configuration Schema",
  "description": "JSON Schema for validating Model Context Protocol server configuration",
  "version": "1.0.0"
}

Impact: Low - Version tracking helps with schema evolution. Main schema would benefit from versioning.

Recommendation: Add a version field to the main schema metadata for consistency.

---

Positive Findings

✅ 1. Complete Field Implementation

All MCP fields are fully implemented across the codebase:

• Schema: Both main_workflow_schema.json and mcp_config_schema.json define all fields correctly
• Parser: pkg/parser/mcp.go extracts all fields (registry, allowed, entrypoint, entrypointArgs, mounts)
• Compiler: pkg/workflow/mcp_config_custom.go processes and renders all fields
• Types: pkg/types/mcp.go defines BaseMCPServerConfig with all properties

✅ 2. Consistent Pattern Validation

Pattern constraints are identical across both schemas:

• env field: Both use ^[A-Z_][A-Z0-9_]*$ for environment variable names
• container field: Both use ^[a-zA-Z0-9][a-zA-Z0-9/:_.-]*$ for container images
• mounts field: Both use ^[^:]+:[^:]+:(ro|rw)$ for mount format validation

✅ 3. Comprehensive Documentation

All MCP fields are documented:

• registry: Documented in docs/src/content/docs/reference/mcp-gateway.md (Section A.5)
• allowed: Documented in docs/src/content/docs/guides/getting-started-mcp.md
• entrypoint: Documented in docs/src/content/docs/reference/mcp-gateway.md (Section A.2)
• entrypointArgs: Documented with examples in MCP Gateway specification
• mounts: Documented in docs/src/content/docs/reference/mcp-gateway.md (Section 4.1.5)

✅ 4. Real-World Usage Validated

Found actual usage of MCP fields in production workflows:

• allowed: Used in 5+ workflows (ai-moderator.md, artifacts-summary.md, auto-triage-issues.md, etc.)
• mounts: Used in hourly-ci-cleaner.md for binding host binaries
• registry: Used in release.md workflow

✅ 5. Extensive Test Coverage

Comprehensive tests exist for all MCP configuration:

• pkg/workflow/mcp_config_comprehensive_test.go - Tests registry and allowed fields
• pkg/workflow/mcp_entrypoint_mounts_integration_test.go - Tests entrypoint and mounts
• pkg/workflow/mcp_gateway_entrypoint_mounts_e2e_test.go - End-to-end validation
• pkg/parser/mcp_test.go - Parser-level tests

✅ 6. Type Safety Across Packages

BaseMCPServerConfig shared between parser and workflow packages eliminates duplication:

// pkg/types/mcp.go
type BaseMCPServerConfig struct {
    // All MCP fields defined with proper JSON/YAML tags
    Command        string            `json:"command,omitempty" yaml:"command,omitempty"`
    Entrypoint     string            `json:"entrypoint,omitempty" yaml:"entrypoint,omitempty"`
    EntrypointArgs []string          `json:"entrypointArgs,omitempty" yaml:"entrypointArgs,omitempty"`
    Mounts         []string          `json:"mounts,omitempty" yaml:"mounts,omitempty"`
    // ... and more
}

✅ 7. Schema Field Parity

Both stdio and HTTP MCP tool definitions in the main schema include all appropriate fields:

• stdio_mcp_tool: 12 properties (allowed, args, command, container, entrypoint, entrypointArgs, env, mounts, network, registry, type, version)
• http_mcp_tool: 5 properties (allowed, headers, registry, type, url)
• MCP config schema: All 14 unique properties (union of stdio and HTTP fields)

✅ 8. No Schema Drift Issues

Unlike previous runs of this strategy (2026-01-24 run found 4 missing properties), all fields are now consistently defined across schemas. The historical schema drift has been resolved.

---

Recommendations

Priority 1: Add Examples to Main Schema

Action: Add the examples array from the MCP config schema to the main schema's env field.

File: pkg/parser/schemas/main_workflow_schema.json

Benefit: Improved IDE autocomplete and developer experience.

Priority 2: Standardize Description Wording

Action: Align the mounts field description wording between schemas.

Files:

• pkg/parser/schemas/main_workflow_schema.json
• pkg/parser/schemas/mcp_config_schema.json

Suggestion: Use the MCP config schema format: "Volume mounts for container (format: 'source:dest:mode' where mode is 'ro' or 'rw')"

Priority 3: Add Version Metadata

Action: Add a version field to the main schema's top-level metadata.

File: pkg/parser/schemas/main_workflow_schema.json

Benefit: Better schema evolution tracking and compatibility management.

---

Strategy Performance

• Strategy Used: Cross-Schema Consistency & Type Analysis (Strategy-004)
• Run Number: 17 (success_count incremented from 16)
• Findings: 3 (0 critical, 1 moderate, 2 minor)
• Effectiveness: ✅ Very High
• Should Reuse: ✅ Yes - Continue using every 4-5 analyses

Strategy Insights

This run demonstrates the continued value of cross-schema validation:

1. Progress Validation: Confirms that the 4 critical schema drift issues from the 2026-01-24 run have been resolved
2. Documentation Quality: Focuses on developer experience improvements (examples, wording consistency)
3. Metadata Completeness: Identifies architectural improvements (schema versioning)

The strategy effectively catches both critical bugs (when they exist) and minor quality improvements (when the code is healthy).

---

Next Steps

1. ✅ Confirm all MCP fields remain implemented and functional
2. 📝 Add examples to main schema env field for better IDE support
3. 📝 Standardize description wording across schemas
4. 📝 Consider adding version metadata to main schema

---

Analysis Date: 2026-01-31
Strategy: Cross-Schema Consistency & Type Analysis (Strategy-004)
Status: ✅ Schemas are highly consistent with excellent implementation coverage
Risk Level: 🟢 Low - Only minor documentation improvements needed

AI generated by Schema Consistency Checker

• expires on Feb 7, 2026, 11:54 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-02-07T23:54:33.763Z.