[Schema Consistency] Implicit Constraint Validation Gaps - December 11, 2025

[github-actions[bot]]

🔍 Schema Consistency Check - December 11, 2025

This analysis examined implicit constraint validation across the schema, parser, compiler, and actual workflow usage to identify gaps where schema constraints aren't enforced in code or where validation logic exists without schema documentation.

Executive Summary

Strategy Used: Strategy-013 (Implicit Constraints & Business Logic Validation)
Inconsistencies Found: 4 categories across minItems, format, uniqueItems, and validation enforcement
Critical Issues: 1 (command.events panic)
Effectiveness: Very High ⭐⭐⭐⭐⭐

Full Analysis Report

Analysis Approach

Strategy-013 focuses on constraint enforcement gaps by:

1. Extracting all JSON Schema constraints (minItems, maximum, pattern, format, uniqueItems)
2. Searching code for validation logic that enforces these constraints
3. Finding business logic rules in code that lack schema representation
4. Identifying format validation in code without corresponding schema format fields
5. Cross-referencing with previous strategy findings (especially Strategy-020 panic analysis)

Critical Issues 🔴

1. command.events Empty Array Can Cause Panic

Schema: properties.on.command.events has minItems: 1 (array must not be empty)

Code: No validation before processing events array

Impact: Strategy-020 previously identified panic condition when events array is empty

Files:

• Schema: pkg/parser/schemas/main_workflow_schema.json (minItems: 1)
• Code: pkg/workflow/comment.go (processes events without validation)

Recommendation: Add validation if len(events) == 0 { return error } or remove minItems=1 if empty is acceptable

---

Moderate Issues ⚠️

2. Format Constraints Missing from Schema

Finding: Schema has ZERO "format" fields despite extensive format validation in code

Code validates these formats:

• URL/URI patterns with wildcard support (*.example.com)
• Cron expressions (with human-friendly parser)
• Docker image names and versions
• Regex patterns for GitHub Actions references

Schema: No "format": "uri", "format": "regex", etc.

Impact:

• IDE autocomplete lacks format hints
• External validators can't check format correctness
• Schema documentation incomplete

Recommendation: Add format constraints to improve schema expressiveness and tooling support

3. uniqueItems Not Validated for network.allowed

Schema: $defs.stdio_mcp_tool.properties.network.properties.allowed has uniqueItems: true

Code: No duplicate detection for allowed domains array

Existing validation: repo_memory.go:274 validates duplicate memory IDs but network domains have no check

Impact: Users can provide duplicate domains without error, leading to redundant configuration

Recommendation: Add duplicate domain validation or remove uniqueItems constraint if duplicates are acceptable

4. minItems=1 Constraints Inconsistently Enforced

Schema defines minItems=1 for 11 array fields:

Field	minItems in Schema	Code Validation
on.command.events	✅	❌ PANIC (critical)
on.schedule	✅	✅ Checked
tools.cache-memory (array)	✅	✅ Checked
tools.repo-memory (array)	✅	⚠️ Not found
safe-outputs.add-labels.allowed	✅	⚠️ Not found
safe-outputs.add-reviewer.reviewers	✅	⚠️ Not found
safe-outputs.assign-milestone.allowed	✅	⚠️ Not found
safe-outputs.link-sub-issue.parent-required-labels	✅	⚠️ Not found
safe-outputs.link-sub-issue.sub-required-labels	✅	⚠️ Not found
roles	✅	⚠️ Not found
stdio_mcp_tool.network.allowed	✅	⚠️ Not found

Status: Most accept empty arrays gracefully (no crash), but schema claims they're invalid

Recommendation: Either add empty array validation or remove minItems=1 constraints for consistency

---

Positive Findings ✅

1. tracker-id Validation: Exemplary Implementation

Schema: minLength: 8, pattern: ^[a-zA-Z0-9_-]+$

Code: pkg/workflow/frontmatter_extraction.go:404-433

• ✅ Validates minimum 8 characters (line 420)
• ✅ Validates pattern character-by-character (lines 425-430)
• ✅ Clear error messages with position and example

Example error: "tracker-id contains invalid character at position 5: '@' (only alphanumeric, hyphens, and underscores allowed)"

Status: PERFECT CONSISTENCY - Code matches schema exactly

2. Maximum Value Handling: Acceptable Pattern

Schema: 20+ fields with maximum constraints (65535, 90, 104857600, 100, etc.)

Code: Uses max values as defaults, relies on schema validation

Example: Safe-outputs max fields

maxCount := 3  // default
if cfg.Max > 0 {
    maxCount = cfg.Max  // use user value
}

Status: ACCEPTABLE - Schema validates on parse, code uses values safely

3. additionalProperties Discipline: Excellent

Schema: 132 instances of "additionalProperties": false

Impact:

• Prevents typos in field names
• Comprehensive field validation
• Clear error messages for unexpected fields

Status: EXEMPLARY - Best practice implementation

4. Conditional Requirements: Well-Implemented

MCP servers: Either 'command' or 'container' required (but not both)

Code: pkg/workflow/mcp_config_validation.go

• ✅ Validates mutual exclusivity
• ✅ Clear error messages with examples
• ✅ Documented in schema descriptions

Error example:

tool 'foo' mcp configuration cannot specify both 'container' and 'command'.
Choose one. Example:
mcp-servers:
  foo:
    command: "node server.js"
Or use container:
mcp-servers:
  foo:
    container: "my-registry/my-tool"
    version: "latest"

5. Safe-Outputs Required Configuration: Consistent Pattern

Finding: 24 functions use consistent pattern to check required configuration

Example: pkg/workflow/add_comment.go:28

if data.SafeOutputs == nil || data.SafeOutputs.AddComment == nil {
    return nil, fmt.Errorf("safe-outputs.add-comment configuration is required")
}

Status: EXCELLENT - Consistent error messages across all safe-output operations

---

Technical Details

Schema Constraint Analysis

Pattern constraints: 14 found

• Action references: ^[a-zA-Z0-9][a-zA-Z0-9/:_.-]*$
• Domain names: ^[a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?)*$
• Docker mounts: ^[^/].*:[^:]+:(ro|rw)$
• Time deltas: ^[0-9]+[dDwWmMyY]$
• tracker-id: ^[a-zA-Z0-9_-]+$

Minimum constraints: 10+ fields with minimum: 1

Maximum constraints: 20+ fields with various upper bounds

Format constraints: 0 (none found)

uniqueItems constraints: 1 field (network.allowed)

minItems constraints: 11 arrays

Business Logic Patterns Found

1. Mutual Exclusivity Validation

• SRT sandbox vs AWF firewall: pkg/workflow/sandbox.go
• MCP command vs container: pkg/workflow/mcp_config_validation.go
• Command vs comment events: pkg/workflow/compiler.go

2. Engine-Specific Feature Validation

• HTTP transport support: pkg/workflow/agent_validation.go:validateHTTPTransportSupport
• max-turns support: pkg/workflow/agent_validation.go:validateMaxTurnsSupport
• web-search support: pkg/workflow/agent_validation.go:validateWebSearchSupport

3. Type Coercion Safety

• ConvertToInt() helper: Defensive conversion with zero fallback
• parseIntValue(): Safe integer parsing for numeric fields
• Logging on type mismatches

---

Comparison to Previous Strategies

Strategy-003 (Required Field Enforcement)

• Focus: Required fields and error messages
• Finding: 'on' required but not enforced (auto-generates default)

Strategy-013 (This Analysis)

• Focus: Value constraints (minItems, maximum, format, uniqueItems)
• Finding: minItems=1 constraints often not enforced

Complementary insights:

• Both found validation gaps where schema declares requirements not enforced
• Both confirmed excellent error message quality
• Strategy-003 focused on presence, Strategy-013 on values

Strategy-020 (Panic Conditions)

• Finding: command.events empty array causes panic
• This analysis: Confirms schema has minItems=1 but code doesn't validate

Integration: Strategy-013 provides schema context for Strategy-020's panic findings

---

Recommendations

Priority 1: Critical 🔴

Fix command.events Empty Array Panic

Add validation in pkg/workflow/comment.go:

if len(events) == 0 {
    return fmt.Errorf("command events array cannot be empty (must specify at least one event)")
}

Or update schema if empty is valid:

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

Priority 2: Medium ⚠️

1. Add Duplicate Domain Validation

In network domain processing:

func validateUniqueItems(domains []string) error {
    seen := make(map[string]bool)
    for _, domain := range domains {
        if seen[domain] {
            return fmt.Errorf("duplicate domain: %s", domain)
        }
        seen[domain] = true
    }
    return nil
}

2. Add Format Constraints to Schema

For URL fields:

{
  "type": "string",
  "format": "uri",
  "description": "..."
}

For cron expressions:

{
  "type": "string",
  "pattern": "^[0-9\\s\\*\\-\\,\\/]+$",
  "description": "Cron expression (standard or human-friendly format)"
}

3. Audit minItems=1 Enforcement

For each field with minItems=1:

• Add explicit empty array validation, OR
• Remove minItems constraint if empty is acceptable
• Document the decision

Priority 3: Low ℹ️

Document Schema Validation Reliance

Add schema comments:

{
  "maximum": 100,
  "description": "Maximum value (validated during schema parse, not re-checked in compiler)"
}

---

Strategy Performance

Findings: 4 categories

1. minItems gaps (11 fields, 1 critical)
2. Format constraints missing (0 in schema, multiple in code)
3. uniqueItems not validated (1 field)
4. Maximum validation pattern (acceptable)

Effectiveness: ⭐⭐⭐⭐⭐ VERY HIGH

Why high effectiveness:

• Found 1 critical panic condition with schema context
• Identified 3 schema documentation improvement areas
• Discovered validation consistency patterns
• Provided actionable recommendations
• Complemented previous strategy findings

Unique value:

• Focus on constraint enforcement rather than field presence
• Systematically examined all JSON Schema constraint types
• Cross-referenced with panic analysis (Strategy-020)
• Identified format validation gap (code validates but schema doesn't document)

---

Files Analyzed

Schema Files:

• pkg/parser/schemas/main_workflow_schema.json (all constraint types)
• pkg/parser/schemas/included_file_schema.json (cross-reference)
• pkg/parser/schemas/mcp_config_schema.json (cross-reference)

Parser/Compiler Files:

• pkg/workflow/frontmatter_extraction.go (tracker-id validation)
• pkg/workflow/comment.go (command events processing)
• pkg/workflow/mcp_config_validation.go (conditional requirements)
• pkg/workflow/sandbox.go (mutual exclusivity)
• pkg/workflow/agent_validation.go (engine-specific features)
• pkg/workflow/safe_outputs.go (configuration required pattern)
• pkg/workflow/cache.go (minItems validation)
• pkg/workflow/repo_memory.go (duplicate validation)

Total: 8 key implementation files, 3 schema files

---

Next Steps

1. ✅ Fix critical panic - Add command.events empty array validation
2. ⚠️ Review minItems constraints - Audit all 11 fields for consistency
3. ⚠️ Add format constraints - Improve schema documentation
4. ℹ️ Document validation approach - Clarify schema vs code validation boundaries

---

Strategy Metadata

• Strategy ID: strategy-013
• Strategy Name: Implicit Constraints & Business Logic Validation
• Success Count: 2 (previous: 2025-11-04, today: 2025-12-11)
• Should Reuse: YES - Use every 5-6 analyses
• Pairs Well With: Strategy-003 (required fields), Strategy-020 (panic conditions), Strategy-017 (type behavior)

Cache Updated: /tmp/gh-aw/cache-memory/strategies.json

AI generated by Schema Consistency Checker

[github-actions[bot]]

⚓ Avast! This discussion be marked as outdated by Schema Consistency Checker.
🗺️ A newer treasure map awaits ye at Discussion #6199.
Fair winds, matey! 🏴‍☠️