[Schema Consistency] Schema Namespace Collision Analysis - 10 Issues Found (1 Critical, 5 High Severity)

[github-actions[bot]]

Overview

This schema consistency audit analyzed field namespace collisions and path ambiguity across the schema. Out of 279 unique field names, 96 fields (34.4%) have name collisions. Most collisions are benign (intentional oneOf patterns), but 10 are problematic, including 1 critical YAML compatibility issue and 5 high-severity naming conflicts.

Key Discovery: The on field (YAML 1.1 reserved keyword) breaks external validation tooling. PyYAML parses it as a boolean, while goccy/go-yaml correctly treats it as a string key.

Full Analysis Report

Critical Finding

🚨 YAML Reserved Keyword - on Field

Severity: CRITICAL
Impact: External tooling ecosystem completely broken

Problem:

• on is a reserved boolean keyword in YAML 1.1 (along with yes, no, off)
• GitHub Actions workflows use on: as a field name
• PyYAML (Python): Parses YAML 1.1 → on: becomes boolean True
• goccy/go-yaml (Go): Uses YAML 1.2 → on: correctly parsed as string key
• All Python/JavaScript validation tools fail on valid gh-aw workflows

Evidence:

# PyYAML behavior:
import yaml
data = yaml.safe_load("on:\n  push:")
# Result: data['on'] = None (or True if alone)

Impact: IDEs, linters, and CI/CD validation tools using PyYAML cannot validate gh-aw workflows.

Recommendations:

1. Document YAML 1.2 parser requirement in schema $comment field
2. Add compatibility warnings in documentation
3. Consider providing YAML 1.2 validation Docker image

---

High Severity Findings

1. Network Configuration Namespace Collision

Severity: HIGH
Field: network

Collision Contexts:

1. $defs.stdio_mcp_tool.network - MCP tool network isolation

   • Controls egress from containerized MCP servers
   • Has allowed array for domain allowlist

2. network - Top-level engine network permissions

   • Controls AI engine network access
   • Has allowed array for ecosystem identifiers and domains
   • Applies firewall rules for engine execution

Problem: Same field name, completely different semantics, no schema disambiguation

Confusion Potential: HIGH - Users might expect engine network rules to apply to MCP servers

Current Documentation: Separate docs (reference/network.md vs guides/mcps.md) without cross-references

Recommendations:

1. Add schema descriptions: "Engine network permissions (not MCP network isolation)"
2. Consider renaming MCP field to network-isolation or egress-allowlist
3. Add explicit cross-references in docs

2. Command Field Overloading (5 Contexts)

Severity: HIGH
Field: command

Collision Contexts:

1. $defs.stdio_mcp_tool.command - MCP server executable command
2. .allOf[0].on.command - Command trigger validation constraint
3. command - Top-level command configuration
4. on.oneOf[1].command - Command event trigger config
5. sandbox.oneOf[1].agent.oneOf[2].command - Agent sandbox command

Confusion Potential: VERY HIGH - "command" means 5 completely different things

Recommendations:

1. Schema descriptions must state context explicitly
2. Documentation should include field path examples (e.g., on.command vs tools.mcp-servers.command)
3. Consider context-specific names (e.g., mcp-command, trigger-command)

3. Environment Variables Scope Hierarchy (13 Contexts)

Severity: HIGH
Field: env

13 Different Scopes:

• Engine config, MCP tool, container, top-level, GitHub Actions steps, jobs, safe-inputs, safe-outputs, agent sandbox, MCP sandbox, services

Problem:

• 13 scopes without documented precedence/merging rules
• Users must infer behavior from GitHub Actions knowledge
• No single source of truth for env var resolution order

Recommendations:

1. Create "Environment Variable Precedence" documentation page
2. Add schema $comment documenting merge order
3. Provide example showing all scopes and their resolution

4. Config Object Hierarchy Ambiguity

Severity: HIGH
Field: config

Collision Contexts:

1. $defs.engine_config.oneOf[1].config - Engine-specific configuration
2. sandbox.oneOf[1].agent.oneOf[2].config - Agent sandbox configuration
3. sandbox.oneOf[1].config - General sandbox configuration

Problem: Generic name "config" at multiple nesting levels - ambiguous without path context

Recommendations:

1. Use specific names: engine-config, agent-config, sandbox-config
2. Add schema descriptions clarifying hierarchy
3. Document field paths in reference docs

5. Permissions Scope Shadowing

Severity: MEDIUM (upgraded from LOW due to GitHub Actions convention)
Field: permissions

Collision Contexts:

1. jobs.permissions - Job-level GitHub permissions
2. permissions - Workflow-level GitHub permissions
3. safe-outputs.jobs.permissions - Safe-outputs job permissions

Problem: Classic shadowing - job-level overrides workflow-level

Current State: Token precedence documented, but not permissions shadowing

Recommendations:

1. Document permissions precedence rules (job > workflow)
2. Add override behavior examples
3. Schema comments explaining scope

---

Medium Severity Findings

6. Runs-On Configuration Precedence

Severity: MEDIUM
Field: runs-on

4 Scope Levels:

• jobs.runs-on
• runs-on (workflow-level)
• safe-outputs.jobs.runs-on
• safe-outputs.runs-on

Problem: Four scopes without clear precedence documentation

Recommendations:

1. Document which runs-on takes precedence
2. Clarify safe-outputs vs main workflow interaction

7. Timeout-Minutes Hierarchy

Severity: MEDIUM
Field: timeout-minutes

4 Scope Levels:

1. githubActionsStep.timeout-minutes
2. jobs.steps.timeout-minutes
3. jobs.timeout-minutes
4. timeout-minutes (workflow-level)

Note: Deprecated in favor of timeout, but still supported

Recommendations:

1. Document timeout-minutes precedence (likely step > job > workflow)
2. Emphasize migration to timeout field
3. Eventually deprecate to reduce collision surface

8. Engine Field Reuse

Severity: MEDIUM
Field: engine

Collision Contexts:

1. engine - Top-level engine configuration (object)
2. safe-outputs.threat-detection.oneOf[1].engine - Threat detection engine (string)

Problem: Same name for object vs string, related but distinct concepts

Recommendations:

1. Schema types make distinction clear
2. Consider renaming threat-detection field to detection-engine or engine-id

9. Timeout Field Namespace Separation

Severity: LOW
Field: timeout

Collision Contexts:

1. safe-inputs.timeout
2. tools.timeout

Status: Acceptable - different namespaces make context clear

Recommendation: Schema descriptions should clarify scope (no action urgently needed)

---

Benign Patterns (Intentional Repetition)

The following fields appear multiple times by design in oneOf/anyOf patterns:

• github-token (29 occurrences) - Safe-outputs configuration pattern
• target, target-repo (11-21 occurrences) - Safe-outputs target specification
• max (24 occurrences) - Safe-outputs limit configuration
• allowed (8 occurrences) - Allowlist patterns across features
• branches, branches-ignore, paths, paths-ignore (3-4 each) - Event filters
• types (19 occurrences) - GitHub event type filters
• version (14 occurrences) - Version specs across tools/configs

These repetitions follow consistent patterns and are structurally necessary.

---

Root Causes

1. Schema Evolution: Fields added over time without namespace planning
2. GitHub Actions Compatibility: Inherited field names (on, env, permissions)
3. Feature Modularity: Same concept (network, config) reused in different subsystems
4. YAML Limitations: Reserved keywords not considered during design
5. Scope Hierarchy: Natural hierarchical scoping creates name reuse

---

Impact Assessment

Critical Impact

• YAML 1.1 compatibility: Breaks external tooling completely
• Parser ambiguity: Risk of incorrect parsing in non-Go tools

High Impact

• User confusion: Network, command, env, config collisions require careful reading
• Documentation burden: Each collision needs explicit disambiguation
• Support burden: Users report "wrong" field behavior when using wrong path

Medium Impact

• Precedence complexity: Permissions, runs-on, timeout-minutes need mental model
• Migration complexity: Deprecated fields still collide

---

Recommendations Summary

Immediate Actions

1. Document YAML parser requirements - Add schema $comment about YAML 1.2 requirement
2. Create precedence documentation - Document env, permissions, runs-on, timeout override rules
3. Add disambiguation examples - Show field paths in docs for collision cases

Short-term Improvements

1. Schema descriptions - Add context-specific descriptions to all colliding fields
2. Documentation cross-references - Link network docs, config docs to explain contexts
3. Error messages - Improve validation errors to include field paths

Long-term Considerations

1. Namespace refactoring - Consider prefixed names (engine-network, mcp-network)
2. Schema versioning - Track breaking changes to field semantics
3. Validation tooling - Provide YAML 1.2 validation Docker image
4. Deprecation strategy - Phase out timeout-minutes to reduce collision surface

---

Positive Findings

1. ✅ Intentional oneOf patterns work well (clear and consistent)
2. ✅ Most collisions follow GitHub Actions conventions (job vs workflow scope)
3. ✅ No broken $ref references - all field paths resolve correctly
4. ✅ Type safety in Go structs enforces correct types at parser level
5. ✅ Most collision fields are individually documented

---

Statistics

• Total unique field names: 279
• Fields with collisions: 96 (34.4%)
• Critical issues: 1 (YAML keyword)
• High severity: 5 (network, command, env, config, permissions)
• Medium severity: 4 (runs-on, timeout-minutes, engine reuse, timeout)
• Benign patterns: 85 (intentional oneOf repetition)

---

Strategy Metadata

Strategy: Namespace Collision & Field Path Ambiguity Detection (Strategy-023)
Novel Approach: ✅ Yes - First analysis focused specifically on naming conflicts
Findings: 10 distinct issues
Effectiveness: VERY HIGH

Methodology:

• Extracted all field paths using Python recursive traversal
• Identified 96 fields appearing in multiple locations
• Analyzed severity for each collision
• Tested YAML 1.1 vs 1.2 parser behavior
• Cross-referenced with documentation
• Built collision taxonomy by root cause and impact

Complementary Strategies:

• Pairs with Strategy-012 (dynamic validation) for YAML parser testing
• Complements Strategy-008 (schema metadata) for adding disambiguation
• Supports Strategy-011 (integration analysis) for context boundaries

---

Next Steps: Review recommendations and prioritize based on user impact. The YAML 1.1 compatibility issue should be addressed first as it blocks external tooling adoption.

---

References:

• §20185414473

AI generated by Schema Consistency Checker

[pelikhan]

/plan

[github-actions[bot]]

🎉 Yo ho ho! Plan Command found the treasure and completed successfully! ⚓💰

#6349

[github-actions[bot]]

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