[Schema Consistency] Schema Constraint Enforcement Gap Analysis - December 15, 2025 #6460

2025-12-15T02:46:51Z

github-actions[bot]
bot Dec 15, 2025

🔍 Schema Consistency Check - December 15, 2025

This analysis reveals a systematic under-constraint problem: the schema accepts values that will fail at runtime or violate external API limits. With zero maxLength constraints on 1,888 string fields and zero maxItems on 1,608 arrays, users can inadvertently create configurations that pass schema validation but fail during execution. This creates a validation gap where external tools cannot catch errors that gh-aw will encounter at runtime.

The findings complement previous analyses (Strategy-023 found schema too strict on 'required' fields, Strategy-024 finds schema too permissive on value bounds) and reveal opportunities to prevent resource exhaustion, DOS attacks, and API rejections through stricter schema validation.

Full Report Details

Summary

Inconsistencies Found: 12 (4 critical, 5 moderate, 3 positive)
Categories Analyzed: Numeric constraints (min/max), String constraints (minLength/maxLength/pattern), Array constraints (minItems/maxItems)
Strategy Used: NEW Strategy 024 - Schema Constraint Enforcement Gap Analysis
New Strategy: YES (day 349 mod 10 = 9, radically different approach)
Fields Analyzed: 3,552 (1,888 strings + 1,608 arrays + 56 numbers)

Critical Issues

1. ⚠️ ZERO maxLength Constraints on ANY String Field

Severity: CRITICAL - 100% of strings unbounded

Issue: The schema has 1,888 string fields, and EXACTLY ZERO have maxLength constraints. This allows unbounded strings that violate GitHub API limits.

Evidence:

Total string fields: 1,888
String fields with maxLength: 0 (ZERO!)
Unconstrained strings: 1,074 (57% have NO constraints at all)

GitHub API Limits NOT Enforced:

Issue title: max 256 characters ❌ Schema allows unlimited
Issue body: max 65,536 characters ❌ Schema allows unlimited
Discussion title: max 256 characters ❌ Schema allows unlimited
Comment body: max 65,536 characters ❌ Schema allows unlimited
Label name: max 50 characters ❌ Schema allows unlimited
Workflow name: max 256 characters ❌ Schema allows unlimited

Real Impact Example:

safe-outputs:
  create_issue:
    title: "[10,000 character string here]"  # Schema validates ✓

Schema validation: PASSES ✓
GitHub API call: FAILS ✗ (exceeds 256 character limit)

Files Affected:

pkg/parser/schemas/main_workflow_schema.json - All string field definitions
pkg/parser/schemas/included_file_schema.json - All string fields
pkg/parser/schemas/mcp_config_schema.json - All string fields

Impact:

Users receive GitHub API errors that should be caught at schema validation
External validation tools cannot prevent API failures
No protection against accidental large payloads (copy-paste errors)
Potential memory exhaustion in parser when handling massive strings

Recommendation:
Add maxLength to all user-facing string fields:

"name": {"type": "string", "maxLength": 256},
"title": {"type": "string", "maxLength": 256},
"body": {"type": "string", "maxLength": 65536},
"campaign": {"type": "string", "minLength": 8, "maxLength": 64},
"command": {"type": "string", "maxLength": 128}

2. ⚠️ ZERO maxItems Constraints on ANY Array

Severity: CRITICAL - DOS attack risk

Issue: The schema has 1,608 array fields, and EXACTLY ZERO have maxItems constraints. This creates DOS vulnerability through unbounded arrays.

Evidence:

Total arrays: 1,608
Arrays with maxItems: 0 (ZERO!)
Arrays without minItems: 1,366 (85% could be empty)

Critical Unbounded Arrays:

network: Domain allowlist (unlimited domains = slow validation)
labels: Workflow labels (unlimited labels = parsing overhead)
@import: Import specifications (unlimited imports = import explosion)
branches: Branch filters (unlimited = regex overhead)
paths: Path filters (unlimited = filesystem traversal overhead)
MCP tool arrays (unlimited tools = slow startup)

DOS Attack Scenario:

network:
  - "*.domain1.com"
  - "*.domain2.com"
  # ... 10,000 more domains

Schema validation: PASSES ✓
Runtime: Network filter overhead causes timeout ✗

Impact:

No protection against DOS via huge arrays
Unbounded network allowlists cause performance degradation
Unlimited MCP tools cause excessive startup delays
Resource exhaustion risk in parser/compiler

Recommendation:
Add maxItems to resource-intensive arrays:

"network": {"type": "array", "maxItems": 100},
"labels": {"type": "array", "maxItems": 20},
"`@import`": {"type": "array", "maxItems": 50},
"branches": {"type": "array", "maxItems": 50}

3. ⚠️ 32 Numeric Fields Without Maximum Bounds

Severity: HIGH - Resource exhaustion risk

Issue: 57% of numeric fields (32 out of 56) lack maximum constraints, allowing absurd values like timeout: 999999999 (31 years).

Critical Unbounded Fields:

Field	Type	Min	Max	Current Risk
`timeout`	integer	1	NONE	Accepts timeout=999999999 (31 years!)
`startup-timeout`	integer	1	NONE	MCP server could wait forever
`max-turns`	integer	0	NONE	Infinite loop risk
`timeout-minutes`	integer	-	NONE	Exceeds GitHub Actions limit (360)
`max` (safe-outputs)	integer	1	NONE	Could create 1 million issues
`expires` (artifacts)	integer	1	NONE	Artifacts expire in 99999 days

Real Examples from Schema:

"timeout": {
  "type": "integer",
  "minimum": 1,
  "description": "Timeout in seconds..."
  // NO MAXIMUM! Accepts 999999999
}

"max": {
  "type": "integer",
  "minimum": 1,
  "description": "Maximum number of items..."
  // NO MAXIMUM! Accepts 1000000
}

Impact Scenarios:

Timeout Overflow:
```
engine:
  timeout: 999999999  # 31 years
```
- Schema: PASSES ✓
- Runtime: Hangs or times out ✗

API Spam:

safe-outputs:
  create_issue:
    max: 1000000  # Create 1 million issues

Schema: PASSES ✓
Runtime: Rate limit hit immediately ✗

Typo Amplification:
```
timeout-minutes: 3000  # User meant 30, typed 3000
```
- Schema: PASSES ✓
- Runtime: Exceeds GitHub Actions max (360) ✗

GitHub Actions Limits Not Enforced:

timeout-minutes: max 360 (6 hours) ❌ Schema allows unlimited
Workflow can specify 999999 minutes (694 days) and schema accepts it

Recommendation:
Add sensible maximum constraints aligned with platform limits:

"timeout": {
  "type": "integer",
  "minimum": 1,
  "maximum": 21600,  // 6 hours (GitHub Actions limit)
  "description": "Timeout in seconds..."
},
"timeout-minutes": {
  "type": "integer",
  "minimum": 1,
  "maximum": 360,  // GitHub Actions maximum
  "description": "Workflow timeout in minutes..."
},
"max": {
  "type": "integer",
  "minimum": 1,
  "maximum": 100,  // Sensible API rate limit
  "description": "Maximum number of items..."
},
"max-turns": {
  "type": "integer",
  "minimum": 0,
  "maximum": 1000,  // Prevent infinite loops
  "description": "Maximum chat iterations..."
}

4. ⚠️ Empty Arrays Accepted Where Invalid

Severity: MEDIUM - Undefined behavior

Issue: 109 arrays lack minItems: 1 constraint, allowing empty arrays that cause runtime errors or undefined behavior.

Evidence:

Arrays without minItems: 109
Arrays that SHOULD require at least one item but don't: Multiple

Problematic Examples:

# Schema ACCEPTS these invalid configurations:

on:
  push:
    branches: []  # Empty - no branches to filter on?

on:
  issues:
    types: []  # Empty - no event types specified?

network: []  # Empty - no domains allowed? Block all?

labels: []  # Empty - pointless but accepted

Good Counter-Example (schedule has minItems: 1):

"schedule": {
  "type": "array",
  "minItems": 1,  // ✓ Requires at least one schedule
  "items": {...}
}

Impact:

Runtime behavior undefined for empty arrays
branches: [] - does it filter nothing? allow all?
types: [] - which events trigger? none?
Workflow author intent unclear

Recommendation:
Add minItems: 1 to arrays that must have values:

"branches": {"type": "array", "minItems": 1, "items": {"type": "string"}},
"types": {"type": "array", "minItems": 1, "items": {"type": "string"}},
"paths": {"type": "array", "minItems": 1, "items": {"type": "string"}}

Documentation Gaps

5. campaign Field: minLength but NO maxLength

Issue: The campaign field requires minimum 8 characters but has no maximum limit.

Schema Definition:

"campaign": {
  "type": "string",
  "minLength": 8,
  "pattern": "^[a-zA-Z0-9_-]+$",
  "description": "Must be at least 8 characters..."
  // Missing: "maxLength": 64
}

Impact:

User could create 10,000 character campaign identifier
Identifier inserted in all created assets (issues, discussions)
Could cause rendering issues or data truncation

Recommendation: Add "maxLength": 64 (sensible identifier length)

6. Pattern Constraints Underutilized

Issue: Only 5% of string fields use pattern constraints for format validation.

Evidence:

String fields: 1,888
With pattern: 89 (5%)
With enum: 681 (36%)
NO constraints: 1,074 (57%)

Fields That SHOULD Have Patterns:

name: Workflow names (should match ^[a-zA-Z0-9_-]+$)
command: Command names (should match ^[a-zA-Z][a-zA-Z0-9_-]*$)
Email addresses (no validation at all)
URLs (no validation at all)

Good Examples Where Patterns ARE Used:

"campaign": {"pattern": "^[a-zA-Z0-9_-]+$"},  // ✓ Identifier format
"domain": {"pattern": "^[a-zA-Z0-9]([a-zA-Z0-9\\-]{0,61}[a-zA-Z0-9])?..."},  // ✓ RFC compliant
"volume": {"pattern": "^[^:]+:[^:]+:(ro|rw)$"}  // ✓ Structured format

Recommendation: Add patterns to user-facing identifier and name fields.

7. Numeric Type Permissiveness

Issue: Many fields accept number (float) when they should be integer, causing silent truncation.

Examples:

timeout: 60.5  # Accepted as "number", truncated to 60
version: 1.0   # Accepted, becomes 1 (loses .0)
expires: 7.8   # 7.8 days? Truncated to 7

Impact:

Silent data loss (60.5 → 60)
User confusion (why did my 60.5 second timeout become 60?)
Inconsistent rounding behavior

Recommendation: Use "type": "integer" for countable values (timeout, max, expires) with clear units in description.

8. Mutually Exclusive Arrays Not Enforced

Issue: Schema comments say branches and branches-ignore are mutually exclusive, but schema doesn't enforce it.

Schema $comment:

"branches": {
  "$comment": "Mutually exclusive with branches-ignore. GitHub Actions requires only one."
}

Problem: Schema allows BOTH simultaneously:

on:
  push:
    branches: ["main"]
    branches-ignore: ["develop"]  # Both specified!

Impact: Runtime behavior undefined if both specified.

Recommendation: Add oneOf constraint:

"oneOf": [
  {"required": ["branches"]},
  {"required": ["branches-ignore"]}
]

9. Format Constraints Completely Unused

Issue: JSON Schema supports format constraints (uri, email, date-time), but gh-aw schemas use ZERO format constraints.

Evidence:

String fields with format constraint: 0 (ZERO!)

JSON Schema Formats Available:

"format": "uri" - URL validation
"format": "email" - Email validation
"format": "date-time" - ISO 8601 dates
"format": "regex" - Regular expressions

Fields That Should Use format:

"url": {"type": "string", "format": "uri"},
"email": {"type": "string", "format": "email"},
"cron": {"type": "string", "format": "regex"}  // Already has pattern, could add format

Impact: Format validation is deferred to parser/compiler instead of being declarative in schema.

Recommendation: Add format constraints to URL and email fields for better IDE integration.

Schema Improvements Needed

Constraint Gap Summary Table

Constraint Type	Total Fields	With Constraint	Without	Gap %
maxLength (strings)	1,888	0	1,888	100%
maxItems (arrays)	1,608	0	1,608	100%
maximum (numbers)	56	24	32	57%
minItems (arrays)	1,608	242	1,366	85%
pattern (strings)	1,888	89	1,799	95%
format (strings)	1,888	0	1,888	100%

Key Insight: Three constraint types have 100% gap (maxLength, maxItems, format) and three have >80% gap (maximum 57%, minItems 85%, pattern 95%). This is a systematic under-constraint problem, not isolated cases.

Parser Updates Required

Finding: Parser does NOT enforce constraints that schema lacks (which is correct behavior).

Validation Analysis:

Parser enforces: What schema defines ✓
Parser does NOT add extra validation beyond schema ✓
Missing schema constraints = missing validation everywhere ✗

Key Files:

pkg/parser/frontmatter.go - Frontmatter parsing (no extra length checks)
pkg/workflow/compiler.go - Main compilation (no extra bound checks)
pkg/workflow/safe_outputs.go - Safe-outputs (no max limit validation)
pkg/workflow/tools.go - Tools config (no array size validation)

Evidence: No length/bound validation in parser code beyond schema:

$ grep -rn "maxLength\|max.*length\|length.*max" pkg/parser/*.go | grep -v test
# No results - parser doesn't add extra validation

$ grep -rn "len(.*) >" pkg/workflow/*.go | grep validate
# No string length validation code

Conclusion: Parser correctly trusts schema. Schema improvements will automatically improve runtime validation.

Workflow Violations

Analysis: Checked 78 production workflows in .github/workflows/*.md for constraint violations.

Findings: NO violations found (workflows stay within sensible bounds)

Actual Values in Production:

timeout values in real workflows:
  3× timeout: 300 (5 minutes)

max values in real workflows:
  50× max: 1
  10× max: 5
   7× max: 10
   6× max: 3
   5× max: 2

Insight: Real workflows are conservative and reasonable. The schema constraint gaps are not currently exploited, but they CREATE RISK for future workflows and external contributions.

No Problematic Patterns Detected:

No extreme timeouts (highest is 300 seconds)
No huge max values (highest is 50)
No empty arrays
No oversized strings

Risk: Absence of violations doesn't mean absence of risk. Schema should prevent invalid values proactively.

Recommendations

Priority 1: Add Maximum Constraints (32 numeric fields)

Critical Fields:

"timeout": {"minimum": 1, "maximum": 21600},  // 6 hours
"startup-timeout": {"minimum": 1, "maximum": 600},  // 10 minutes
"timeout-minutes": {"minimum": 1, "maximum": 360},  // GitHub Actions max
"max-turns": {"minimum": 0, "maximum": 1000},  // Prevent infinite loops
"max": {"minimum": 1, "maximum": 100},  // API rate limit
"expires": {"minimum": 1, "maximum": 400}  // GitHub max retention

Impact: Prevents resource exhaustion and catches typos before runtime.

Priority 2: Add maxLength to Strings (1,888 fields)

GitHub API-Facing Fields (highest priority):

"title": {"maxLength": 256},  // GitHub API limit
"body": {"maxLength": 65536},  // 64KB GitHub API limit
"name": {"maxLength": 256},  // GitHub Actions limit
"campaign": {"maxLength": 64},  // Sensible identifier length
"command": {"maxLength": 128},  // Command name length
"label": {"maxLength": 50}  // GitHub label limit

Impact: Prevents GitHub API rejections at validation time instead of runtime.

Priority 3: Add maxItems to Arrays (1,608 arrays)

Resource-Intensive Arrays:

"network": {"maxItems": 100},  // Prevent network filter DOS
"labels": {"maxItems": 20},  // Reasonable workflow label limit
"`@import`": {"maxItems": 50},  // Prevent import explosion
"branches": {"maxItems": 50},  // Reasonable branch filter limit
"paths": {"maxItems": 100}  // Reasonable path filter limit

Impact: Prevents DOS attacks and performance degradation.

Priority 4: Add minItems: 1 (109 arrays)

Arrays That Must Have Values:

"branches": {"minItems": 1},  // At least one branch required
"types": {"minItems": 1},  // At least one event type required
"paths": {"minItems": 1}  // At least one path required

Impact: Prevents undefined behavior from empty arrays.

Priority 5: Add format Constraints

URL and Email Fields:

"url": {"format": "uri"},
"email": {"format": "email"},
"date": {"format": "date-time"}

Impact: Better IDE integration and validation tooling support.

Positive Findings

✅ minItems Used Correctly for Critical Arrays

Good Examples:

"schedule": {"type": "array", "minItems": 1}  // Can't be empty ✓

The schedule array correctly requires at least one cron expression. This prevents the common mistake of empty schedule arrays.

✅ Pattern Constraints Are Excellent Where Used

High-Quality Patterns:

"campaign": {"pattern": "^[a-zA-Z0-9_-]+$"},  // Clean identifier format
"domain": {"pattern": "^[a-zA-Z0-9]([a-zA-Z0-9\\-]{0,61}[a-zA-Z0-9])?..."},  // RFC 1035 compliant!
"volume": {"pattern": "^[^:]+:[^:]+:(ro|rw)$"},  // Structured Docker volume format
"extension": {"pattern": "^\.[a-zA-Z0-9]+$"}  // File extension format

The patterns that DO exist are well-crafted, RFC-compliant, and precise. The issue is not pattern quality but pattern coverage (only 5% of strings).

✅ Minimum Constraints Used Consistently

Good Examples:

"timeout": {"minimum": 1},  // No zero/negative timeouts
"max": {"minimum": 1},  // At least one item
"expires": {"minimum": 1}  // Can't expire in 0 days

All timeout and count fields correctly enforce minimum: 1 to prevent obviously invalid values (zero or negative).

Strategy Performance

Strategy Used: NEW Strategy 024 - Schema Constraint Enforcement Gap Analysis
Findings: 12 (4 critical, 5 moderate, 3 positive)
Effectiveness: VERY HIGH
Should Reuse: YES (every 5-6 analyses)

Unique Value:

First strategy to systematically analyze MISSING constraints
Complements Strategy-023 (which found schema too strict on 'required')
Reveals opposite problem: schema too permissive on value bounds
Analyzed 3,552 fields across 3 constraint dimensions

Key Metrics:

100% gap: maxLength, maxItems, format
85%+ gap: minItems, pattern
57% gap: maximum
Critical findings: 4 out of 12 (33% critical rate)

Methodology Strengths:

Quantitative analysis (counted every field by type)
Cross-referenced with external limits (GitHub API)
Validated against real workflow usage patterns
Provided specific schema change recommendations

Next Steps

Immediate Actions

Add maximum constraints to 32 numeric fields (Priority 1)
- Focus on timeout, max, max-turns, expires fields
- Align with GitHub Actions limits (360 minutes)
- Prevent resource exhaustion
Add maxLength to GitHub API-facing string fields (Priority 2)
- title: 256, body: 65536, label: 50
- Prevents API rejections
- 10-15 critical fields first
Add maxItems to network and import arrays (Priority 3)
- network: 100, @import: 50, labels: 20
- Prevents DOS attacks
- 5-10 critical arrays first

Schema Enhancement Process

Phase 1 (Critical): Maximum constraints on numeric fields (2-3 hours)
Phase 2 (High): maxLength on GitHub API fields (3-4 hours)
Phase 3 (High): maxItems on resource arrays (2-3 hours)
Phase 4 (Medium): minItems: 1 on required arrays (1-2 hours)
Phase 5 (Low): format constraints on URLs/emails (1 hour)

Total Effort: ~10-15 hours to address all findings

Testing Requirements

After schema changes:

Validate all 78 production workflows still pass
Test boundary values (max-1, max, max+1)
Verify error messages are clear
Update documentation with new constraints

Comparison with Previous Findings

Strategy-023 (Dec 14): Schema too STRICT

Found: 'on' field marked required but compiler auto-generates it
Pattern: Schema says required, runtime makes it optional

Strategy-024 (Dec 15): Schema too PERMISSIVE

Found: All string/array/numeric fields lack maximum bounds
Pattern: Schema says valid, runtime will reject (API limits)

Combined Insight: Schema diverges from runtime reality in BOTH directions:

Too strict: Requires fields that are actually optional (auto-generated)
Too permissive: Accepts values that are actually invalid (exceed limits)

Resolution Path: Both findings require schema updates to match runtime behavior.

References:

pkg/parser/schemas/main_workflow_schema.json - Main schema file (3,552 fields analyzed)
pkg/parser/schemas/included_file_schema.json - Included file schema
pkg/parser/schemas/mcp_config_schema.json - MCP configuration schema

AI generated by Schema Consistency Checker

2025-12-16T02:40:44Z

github-actions[bot]
bot Dec 16, 2025
Author

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

0 replies

[Schema Consistency] Schema Constraint Enforcement Gap Analysis - December 15, 2025 #6460

Uh oh!

github-actions[bot] bot Dec 15, 2025

🔍 Schema Consistency Check - December 15, 2025

Summary

Critical Issues

1. ⚠️ ZERO maxLength Constraints on ANY String Field

2. ⚠️ ZERO maxItems Constraints on ANY Array

3. ⚠️ 32 Numeric Fields Without Maximum Bounds

4. ⚠️ Empty Arrays Accepted Where Invalid

Documentation Gaps

5. campaign Field: minLength but NO maxLength

6. Pattern Constraints Underutilized

7. Numeric Type Permissiveness

8. Mutually Exclusive Arrays Not Enforced

9. Format Constraints Completely Unused

Schema Improvements Needed

Constraint Gap Summary Table

Parser Updates Required

Workflow Violations

Recommendations

Priority 1: Add Maximum Constraints (32 numeric fields)

Priority 2: Add maxLength to Strings (1,888 fields)

Priority 3: Add maxItems to Arrays (1,608 arrays)

Priority 4: Add minItems: 1 (109 arrays)

Priority 5: Add format Constraints

Positive Findings

✅ minItems Used Correctly for Critical Arrays

✅ Pattern Constraints Are Excellent Where Used

✅ Minimum Constraints Used Consistently

Strategy Performance

Next Steps

Immediate Actions

Schema Enhancement Process

Testing Requirements

Comparison with Previous Findings

Replies: 1 comment

Uh oh!

github-actions[bot] bot Dec 16, 2025 Author

github-actions[bot]
bot Dec 15, 2025

github-actions[bot]
bot Dec 16, 2025
Author