[Schema Consistency] Field Dependency & Interaction Inconsistencies - 2026-02-08

[github-actions[bot]]

Summary

Comprehensive analysis of field dependencies and interactions across schema, parser, documentation, and real workflows revealed 7 inconsistencies.

• Analysis Date: 2026-02-08
• Strategy: Cross-Component Interaction Analysis (novel approach)
• Focus Areas: oneOf alternatives, mutual exclusivity, conditional dependencies
• Files Analyzed: 1 schema + 25+ parser files + 5+ docs + 50+ workflows

Inconsistency Breakdown:

• Schema enforcement gaps: 2
• Documentation clarity gaps: 4
• Parser/validation gaps: 2

Critical Issues

🔴 Missing JSON Schema enforcement for mutual exclusivity

The schema documents mutually exclusive fields (branches/branches-ignore, paths/paths-ignore) in $comment fields but doesn't use JSON Schema's not constraint to enforce them.

Evidence:

• Schema: pkg/parser/schemas/main_workflow_schema.json:292, 300, 308, 316
• Parser validation exists: pkg/workflow/compiler_filters_validation.go:87-103
• JSON Schema constraint: Missing

Impact: Schema validation tools won't catch these errors; only the compiler validates them at runtime.

Recommendation: Add JSON Schema allOf + not constraints:

{
  "allOf": [
    {
      "not": {
        "required": ["branches", "branches-ignore"]
      }
    }
  ]
}

---

🟡 allow-urls requires ssl-bump but dependency not enforced

Schema documents: "URL patterns to allow for HTTPS traffic (requires ssl-bump: true)" but there's no validation enforcing this dependency.

Evidence:

• Schema description: pkg/parser/schemas/main_workflow_schema.json:2180
• Parser usage: pkg/workflow/firewall.go:207
• Validation check: Not found
• Documentation confirms: docs/src/content/docs/reference/network.md

Impact: Users could specify allow-urls without ssl-bump, leading to silent failure or confusion.

Recommendation: Add validation in pkg/workflow/frontmatter_extraction_security.go or firewall.go.

---

Documentation Gaps

View oneOf Format Documentation Issues (4 findings)

Finding: oneOf alternatives not consistently explained

The schema defines 14 fields with oneOf alternatives (string|object, boolean|string, etc.):

• on (string | object)
• permissions (string enum | object)
• runs-on (string | array | object)
• concurrency (string | object)
• env (object | string)
• environment (string | object)
• container (string | object)
• network (string enum | object)
• sandbox (boolean | string enum | object)
• plugins (array | object)
• steps (object | array)
• post-steps (object | array)
• cache (object | array)
• roles (string enum "all" | array)

Specific gaps:

1. env string format: Schema allows env: string but it's not documented or clearly handled in parser

   • Schema: oneOf includes type: string
   • Parser: Only handles map[string]any in pkg/workflow/frontmatter_extraction_security.go:312
   • Recommendation: Remove from schema or document purpose

2. sandbox boolean option: Schema includes boolean but docs don't cover it

   • Schema: oneOf: [boolean, string, object]
   • Parser: Handles boolean in pkg/workflow/frontmatter_extraction_security.go:173-177 (logs warning)
   • Documentation: Missing
   • Recommendation: Document that sandbox: true has no effect (treated as unconfigured)

3. cache array format: Multiple caches allowed but unclear when to use

   • Schema: oneOf: [object, array]
   • Real usage: 2 workflows use array (layout-spec-maintainer.md, prompt-clustering-analysis.md)
   • Recommendation: Add multi-cache use case documentation

4. roles semantics: Difference between "all" string vs array unclear

   • Schema: oneOf: [string enum "all", array]
   • Real usage: .github/workflows/release.md uses roles: [admin, maintainer]
   • Recommendation: Clarify "all" = all authenticated users vs specific role array

---

Schema Improvements Needed

1. Add JSON Schema not constraints for mutually exclusive fields (branches/branches-ignore, paths/paths-ignore)
2. Add dependentRequired for allow-urls → requires ssl-bump: true
3. Add dependentRequired for ssl-bump → should validate AWF sandbox (or document SRT behavior)
4. Review env: string oneOf option - appears unused, consider removing
5. Add descriptions explaining when to use each oneOf alternative

---

Parser Updates Required

1. Add validation: allow-urls requires ssl-bump: true

   • Location: pkg/workflow/firewall.go or frontmatter_extraction_security.go
   • Check: If allow-urls exists, ensure ssl-bump is true

2. Add validation: ssl-bump with non-AWF sandbox

   • Location: pkg/workflow/firewall.go
   • Check: If ssl-bump: true, validate sandbox type is AWF or document SRT behavior

3. Clarify env: string handling

   • Location: pkg/workflow/frontmatter_extraction_security.go
   • Decision needed: Is string format supported? If not, add validation error

---

Recommendations

1. High Priority: Add allow-urls → ssl-bump dependency validation (prevents user confusion)
2. High Priority: Enhance schema with JSON Schema not constraints for mutual exclusivity
3. Medium Priority: Document oneOf format alternatives with "when to use" guidance
4. Medium Priority: Review and remove unused env: string format from schema
5. Low Priority: Add ssl-bump + sandbox type validation or document behavior

---

Strategy Performance

Strategy Name: Cross-Component Interaction Analysis

What made it unique:

• Focused on field relationships rather than individual fields
• Systematically analyzed all oneOf/anyOf alternatives (14 fields)
• Searched for implicit dependencies in schema descriptions
• Validated that documented constraints are enforced in code
• Cross-referenced real workflow usage patterns

Effectiveness: ⭐⭐⭐⭐

• 7 inconsistencies found
• Discovered new categories: mutual exclusivity enforcement, conditional dependencies, oneOf clarity
• Complements previous strategies (field enumeration, type constraints)
• Reuse recommendation: YES - fills gaps missed by other approaches

Novel insights:

• Schema comments document constraints that JSON Schema could enforce automatically
• Many oneOf alternatives lack "when to use which format" guidance
• Parser has conditional field logic (e.g., allow-urls requires ssl-bump) not validated

---

Analysis Methodology

# 1. Extract oneOf structures from schema
jq -r '.properties | to_entries[] | select(.value.oneOf)' schema.json

# 2. Find implicit dependencies in descriptions
jq -r '.properties | to_entries[] | 
  select(.value.description | test("requires?|depends?"))' schema.json

# 3. Check parser validation for dependencies
grep -rn "allow-urls\|ssl-bump" pkg/workflow/

# 4. Analyze real workflow patterns
grep -A10 "^network:" .github/workflows/*.md
grep -A5 "^cache:" .github/workflows/*.md

# 5. Cross-reference with documentation
grep -rn "ssl-bump\|oneOf" docs/src/content/docs/reference/

---

References:

• Workflow Run: §21793784003

AI generated by Schema Consistency Checker

• expires on Feb 15, 2026, 6:44 AM UTC