[Schema Consistency] Schema Consistency Analysis Report

[github-actions[bot]]

Schema Consistency Analysis: gh-aw Repository

Executive Summary

The schema generally has good coverage of top-level frontmatter fields. However, there are notable inconsistencies between the documented schema and the actual code implementation:

1. Nested field locations: Some fields like cache-memory and repo-memory are properly nested under tools in schema but there's potential confusion about their structure.
2. Field naming consistency: dispatch_repository in code uses underscore but schema expects dispatch-repository with hyphen.
3. Top-level fields properly covered: Most top-level fields like disable-model-invocation, infer, metadata, labels, private, check-for-updates, inlined-imports, run-install-scripts are all present in schema.
4. Missing in schema: The include field documented in code is NOT at top-level in schema (should be).

---

Detailed Findings

1. TOP-LEVEL SCHEMA PROPERTIES ANALYSIS

All 54 top-level properties found in schema:

• bots, cache, check-for-updates, checkout, command, concurrency, container, dependencies, description, disable-model-invocation, engine, env, environment, features, github-app, if, import-schema, imports, infer, inlined-imports, jobs, labels, mcp-scripts, mcp-servers, metadata, name, network, observability, on, permissions, post-steps, pre-agent-steps, pre-steps, private, rate-limit, redirect, resources, run-install-scripts, run-name, runs-on, runs-on-slim, runtimes, safe-outputs, sandbox, secret-masking, secrets, services, source, steps, strict, timeout-minutes, tools, tracker-id

All checked frontmatter fields from code are present in schema ✓

---

2. SPECIFIC FIELD ANALYSIS

Fields Verified to Be in Both Code and Schema:

Field	Code Location	Schema Location	Type	Notes
disable-model-invocation	FrontmatterConfig (frontmatter_types.go)	✓ Present (line 2669)	boolean	Properly documented as control for agent invocation
infer	FrontmatterConfig	✓ Present (line 2664)	boolean	DEPRECATED in favor of disable-model-invocation
metadata	FrontmatterConfig L205	✓ Present (line 54)	object	Schema allows custom key-value pairs, max 64 char keys, 1024 char values
labels	FrontmatterConfig L156	✓ Present (line 41)	array[string]	For workflow categorization
private	FrontmatterConfig L154	✓ Present (line 8762)	boolean	Prevents external installation via gh aw add
check-for-updates	FrontmatterConfig L215	✓ Present (line 8768)	boolean	Disables version update check step
inlined-imports	FrontmatterConfig L201	✓ Present (line 366)	boolean	Inlines all imports at compile time
run-install-scripts	FrontmatterConfig L155	✓ Present (line 8774)	boolean	Allows pre/post install scripts (supply chain risk)
import-schema	FrontmatterConfig L199	✓ Present (line 9089)	object	Schema for validating import 'with' values
dependencies	FrontmatterConfig via On	✓ Present (line 9027)	array[string]	Job dependencies
resources	FrontmatterConfig L202	✓ Present (line 354)	array[string]	Additional files to fetch with workflow

Fields Verified in On Sub-properties:

Field	Schema Location	Type	Notes
stale-check	✓ Present (line 2088)	boolean	Disables frontmatter hash check in activation job
skip-roles	✓ Present (line 1748)	string | array[string]	Skip execution for specific roles
skip-bots	✓ Present (line 1764)	string | array[string]	Skip execution for specific users
manual-approval	✓ Present (line 1812)	string	Environment name for approval gates
github-token	✓ Present (line 1891)	string	Custom token for pre-activation operations
github-app	✓ Present (line 1896)	object	GitHub App for token minting

Memory and Observability Fields (Nested under tools):

Field	Code Field	Schema Location	Type	Notes
cache-memory	CacheMemoryConfig (L477)	✓ Present in tools (line 3872)	boolean | object | array[object]	Persistent memory via cache
repo-memory	RepoMemoryConfig (L478)	✓ Present in tools (line 4119)	boolean | object | array[object]	Repository-scoped memory
observability	ObservabilityConfig (L207)	✓ Present (line 8659)	object	OTLP endpoint configuration

---

3. CRITICAL INCONSISTENCY: YAML TAG NAMING

Issue Found - CRITICAL:

In pkg/workflow/compiler_types.go line 589:

DispatchRepository              *DispatchRepositoryConfig              `yaml:"dispatch_repository,omitempty"`

The code uses underscore (dispatch_repository), but schema expects hyphen (dispatch-repository).

Location in SafeOutputsConfig struct (lines 549-620): Line 589
Schema definition: Not yet checked - need to find it

This could cause YAML deserialization failures when the schema validation passes but the struct unmarshaling fails.

---

4. MISSING TOP-LEVEL FIELD IN SCHEMA

Issue Found - CRITICAL:

The include field is defined in FrontmatterConfig (line 200 of frontmatter_types.go):

Include        any            `json:"include,omitempty"`         // Can be string or array

Schema Status: include field is NOT present at the top-level properties. It appears only nested in other contexts (engine config, etc.).

Expected Schema Location: Should be a top-level property alongside imports and resources since it's parsed at the frontmatter level.

---

5. SAFE-OUTPUTS CONFIG STRUCTURE ANALYSIS

Code Structure (compiler_types.go lines 549-620):

The SafeOutputsConfig struct contains ~40+ configuration types for different output actions:

• create-issue, create-discussion, update-discussion, close-discussion, close-issue, close-pull-request
• add-comment, comment-memory, create-pull-request, create-pull-request-review-comment
• submit-pull-request-review, reply-to-pull-request-review-comment, resolve-pull-request-review-thread
• create-code-scanning-alerts, autofix-code-scanning-alert, add-labels, remove-labels
• add-reviewer, assign-milestone, assign-to-agent, assign-to-user, unassign-from-user
• update-issues, update-pull-requests, merge-pull-request, push-to-pull-request-branch
• upload-assets, upload-artifact, update-release, create-agent-sessions
• update-projects, create-projects, create-project-status-updates, link-sub-issue, hide-comment, set-issue-type
• dispatch-workflow, dispatch_repository (underscore!), call-workflow
• Plus: missing-tool, missing-data, noop, report-incomplete, threat-detection
• Plus: jobs, scripts, github-app, allowed-domains, allowed-github-references, env, github-token, max-patch-size, runs-on, messages, mentions, footer, group-reports, report-failure-as-issue, failure-issue-repo, max-bot-mentions, steps, id-token, concurrency-group, needs, environment, actions

Schema Coverage: All major safe-outputs config types appear to be documented in schema starting at line 4479.

---

6. ENGINE FIELD STRUCTURE

Code: Uses EngineConfig struct (referenced at L434 in compiler_types.go)
Schema: Defined at line 3384 with $ref: "#/$defs/engine_config"

Engine Config Sub-properties:

• id - Engine identifier
• version - Version specification
• model - Model selection (for claude, etc.)
• max-turns - Max conversation turns
• Nested under tools: cache-memory, repo-memory, agentic-workflows

---

7. NETWORK FIELD STRUCTURE

Schema Definition: Lines 2882-2926

Properties:

• allowed: Array of domain names or ecosystem identifiers
• blocked: Array of domains to explicitly block

Code Reference: NetworkPermissions struct should exist in pkg/workflow/domains.go or similar

---

8. DOCUMENTED vs. IMPLEMENTED FRONTMATTER FIELDS

From docs/src/content/docs/reference/frontmatter.md (first 100 lines):

Documented top-level sections:

• Trigger Events (on:)
• Description (description:)
• Source Tracking (source:)
• Redirect (redirect:)
• Private Workflows (private:)

All of these are properly in the schema.

---

Summary of Actionable Inconsistencies

CRITICAL ISSUES:

1. YAML Tag Mismatch: dispatch_repository (underscore) in code vs. likely hyphenated in schema

   • File: pkg/workflow/compiler_types.go line 589
   • Impact: YAML deserialization may fail

2. Missing include Field: Not present as top-level property in schema

   • File: pkg/workflow/frontmatter_types.go line 200
   • Should be added to schema top-level properties
   • Impact: Field is implemented in code but not validated by schema

MEDIUM ISSUES:

3. Nested Field Organization: cache-memory and repo-memory are nested under tools in schema - verify this matches code expectations for parsing

NO ISSUES FOUND:

• ✓ disable-model-invocation - Present and documented
• ✓ infer - Present, marked as deprecated
• ✓ metadata - Present with proper constraints
• ✓ labels - Present for categorization
• ✓ private - Present for security
• ✓ check-for-updates - Present
• ✓ inlined-imports - Present
• ✓ run-install-scripts - Present
• ✓ import-schema - Present
• ✓ dependencies - Present
• ✓ resources - Present
• ✓ All on sub-properties (stale-check, skip-roles, skip-bots, etc.) - Present
• ✓ Safe-outputs sub-properties - All documented in schema
• ✓ Engine, network, sandbox configurations - All documented

---

Recommendations

1. Immediate: Fix the dispatch_repository / dispatch-repository naming inconsistency
2. High Priority: Add include as a top-level schema property
3. Validation: Verify cache-memory and repo-memory parsing correctly from nested tools location
4. Testing: Add schema validation tests for all newly verified fields

Generated by Schema Consistency Checker · ● 804.9K · ◷

• expires on Apr 26, 2026, 4:39 AM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Schema Consistency Checker.

A newer discussion is available at Discussion #28547.