[Schema Consistency] Schema Completeness & Metadata Quality Audit - February 2026

[github-actions[bot]]

Summary

Comprehensive schema metadata quality analysis comparing current state against the January 12, 2026 baseline.

• Strategy: Schema Completeness & Internal Reference Analysis (Strategy 008)
• Improvements Found: 4 major improvements since last run
• Persistent Gaps: 2 architectural gaps remain
• New Issues: 0 (validation only)
• Status: ✅ Excellent validation quality improvements confirmed

🎉 Major Improvements Since 2026-01-12

1. maxItems Constraints Added

• Previous: 0 maxItems constraints
• Current: 20 maxItems constraints
• Impact: Arrays now have proper upper bounds (balanced 1:1 with minItems)
• Status: ✅ EXCELLENT IMPROVEMENT

2. Pattern Constraints Expanded

• Previous: Only 6 pattern constraints
• Current: 28 pattern constraints
• Impact: 4.6x increase in regex validation coverage
• Status: ✅ EXCELLENT IMPROVEMENT

View Pattern Constraint Examples

# Examples of new pattern constraints
tracker-id: ^[a-zA-Z0-9_-]+$
sandbox.mcp.container: ^[a-zA-Z0-9][a-zA-Z0-9/:_.-]*$
branch-prefix: ^[a-zA-Z0-9_-]+$
target-repo: ^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$

3. Top-Level Metadata Complete

• Previous: "All three schemas missing top-level metadata ($id, title, description)"
• Current: Both schemas have complete metadata
• Impact: Better IDE integration and schema discoverability
• Status: ✅ FIXED

4. maxLength Constraints Doubled

• Previous: Only 3 maxLength constraints
• Current: 6 maxLength constraints
• Status: ✅ IMPROVEMENT (still limited coverage)

⚠️ Persistent Architectural Gaps

1. Zero Format Constraints

• Finding: No URI, email, date-time, or regex format validation markers
• Impact: Cannot leverage JSON Schema validator's built-in format validation
• Fields Affected: URLs, GitHub tokens, email addresses, date fields
• Status: Persistent finding (unchanged since 2026-01-12)
• Recommendation: Add format constraints where applicable

Example Format Constraint Opportunities

{
  "github-token": {
    "type": "string",
    "format": "uri-template",
    "pattern": "^\\$\\{\\{.*\\}\\}$"
  },
  "project": {
    "type": "string", 
    "format": "uri",
    "pattern": "^(github/redacted)\\.com/.*"
  }
}
``````

</details>

#### 2. Low Example Coverage (11%)
- **Finding**: Only 74 of 677 fields (11%) have explicit examples
- **Impact**: Reduced schema discoverability and IDE autocomplete quality
- **Critical Fields Missing Examples**:
  - `github-token` (authentication)
  - `roles` (security/access control)
  - `bots` (automation triggers)
  - `timeout-minutes` (workflow timing)
  - `cache`, `cache-memory` (performance)

- **Status**: Persistent finding (was 89+ fields, now 603 fields - either regression or more thorough analysis)
- **Recommendation**: Prioritize examples for security-critical and commonly-used fields

### 📊 Schema Quality Scorecard

| Category | Score | Status | Notes |
|----------|-------|--------|-------|
| Top-level metadata | 100% | ✅ | All schemas complete |
| $ref consistency | 100% | ✅ | Zero broken references |
| $defs usage | 100% | ✅ | All 5 definitions properly referenced |
| Description coverage | 100% | ✅ | All 677 fields have descriptions |
| Example coverage | 11% | ❌ | Only 74/677 fields have examples |
| Explicit defaults | 14% | ⚠️ | 30 explicit vs 179 text-described |
| Pattern constraints | Limited | ⚠️ | 28 patterns (good progress from 6) |
| Format constraints | 0% | ❌ | Zero format markers |
| maxItems constraints | NEW | ✅ | 20 constraints added |
| String bounds | Partial | ⚠️ | 19 minLength, 6 maxLength (3:1 ratio) |

### 🔍 Detailed Analysis

#### Internal Reference Health

All internal schema references are valid and properly used:

- **$ref validation**: 35 valid references, 0 broken references
- **$defs usage**: All 5 definitions actively used
  - `engine_config`: 2 references
  - `github_token`: 30 references
  - `stdio_mcp_tool`: 1 reference
  - `http_mcp_tool`: 1 reference
  - `githubActionsStep`: 3 references

#### Constraint Distribution

``````
Constraint Type              Count    Notes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
minLength                       19    Lower bounds for strings
maxLength                        6    Upper bounds (limited)
minimum                         52    Lower bounds for numbers
maximum                         30    Upper bounds for numbers
minItems                        20    Lower bounds for arrays
maxItems                        20    Upper bounds for arrays ✅ NEW
pattern                         28    Regex validation ✅ 4.6x increase
format                           0    JSON Schema formats ❌
additionalProperties           183    Strict typing enforcement
required                       107    Required field arrays
``````

#### Text-Described vs Explicit Defaults

**Finding**: 179 fields describe defaults in text but lack explicit "default" field

<details>
<summary><b>View Examples of Text-Described Defaults</b></summary>

``````
roles:
  Description: "Defaults to ['admin', 'maintainer', 'write'] for security"
  Explicit default: None

timeout-minutes:
  Description: "Defaults to 20 minutes for agentic workflows"
  Explicit default: None

name:
  Description: "If not specified, defaults to the filename without extension"
  Explicit default: None

on.slash_command.events:
  Description: "Default is all comment-related events ('*')"
  Explicit default: None

Impact: IDE tools may not show default values in autocomplete or validation

Recommendation: Convert text descriptions to explicit "default" fields or $comment annotations

📋 Recommendations

Priority 1: Developer Experience (High Impact, Low Effort)

1. Add examples to security-critical fields

   • github-token: Show secret reference patterns
   • roles: Show common permission combinations
   • bots: Show bot trigger patterns

2. Add examples to commonly-used fields

   • cache: Show GitHub Actions cache patterns
   • timeout-minutes: Show typical timeout values
   • environment: Show environment configuration

Priority 2: Schema Formalization (Medium Impact, Medium Effort)

3. Convert text-described defaults to explicit defaults

   • 179 fields currently describe defaults only in text
   • Use explicit "default" field for simple values
   • Use $comment for complex conditional defaults

4. Add format constraints for structured strings

   • URIs: "format": "uri" for GitHub URLs
   • URI templates: "format": "uri-template" for token expressions
   • Consider custom formats for domain-specific patterns

Priority 3: Validation Completeness (Low Impact, High Effort)

5. Expand maxLength constraints

   • Currently only 6 maxLength vs 19 minLength (3:1 ratio)
   • Add upper bounds for string fields where applicable
   • Prevents potential DoS via extremely long strings

6. Add more pattern constraints

   • Good progress (6 → 28), but opportunities remain
   • Consider patterns for version strings, branch names, identifiers

🎯 Comparison with Strategy Goals

From strategy-008 history:

Goal	Status	Notes
Fix top-level metadata	✅ FIXED	Was critical finding, now complete
Maintain $ref consistency	✅ MAINTAINED	Zero broken references
Add maxItems constraints	✅ ADDED	Was architectural gap, now complete (20 constraints)
Improve example coverage	⚠️ PERSISTENT	Still critical gap at 11%
Add format constraints	❌ PERSISTENT	Still zero (unchanged)
Formalize text defaults	⚠️ PERSISTENT	179 fields affected

📈 Strategy Performance

• Strategy Used: Schema Completeness & Internal Reference Analysis
• Findings: 9 total (4 improvements, 3 persistent gaps, 2 new metrics)
• Effectiveness: Very High
• Should Reuse: Yes (every 4-5 analyses recommended)
• Complements: Strategy 007 (Example Validation), Strategy 012 (Dynamic Validation)

🏁 Overall Assessment

Excellent Progress: Schema infrastructure has significantly improved since 2026-01-12. The addition of maxItems constraints, expansion of pattern validation, and completion of top-level metadata demonstrate strong commitment to schema quality.

Remaining Work: Focus should shift to documentation and developer experience:

• Example coverage remains the most critical gap (11%)
• Format constraints represent untapped validation potential
• Text-described defaults could be formalized for better tooling support

Next Steps:

• Add examples to root-level fields (Priority 1)
• Consider format constraints for structured strings (Priority 2)
• Continue monitoring constraint coverage with this strategy every 4-5 analyses

References:

• §21572583065

AI generated by Schema Consistency Checker

• expires on Feb 8, 2026, 11:55 PM UTC