[Schema Consistency] Schema Consistency Check — 2026-04-03

[github-actions[bot]]

Analysis of schema, parser/compiler, documentation, and workflows using the Cross-Layer Field Diff strategy (proven, success_count: 5). Most recent commit analyzed: c0865b8 — feat: Expose MCP gateway keepalive-interval in workflow config schema.

Summary

Metric	Value
Strategy	Cross-Layer Field Diff (proven, reused)
New strategy	No
Total inconsistencies	10
Critical (potential bugs)	1
Schema ↔ Parser mismatches	1
Schema description inaccuracies	1
Documentation gaps	7
Naming inconsistencies	1
Workflow violations	0 ✅

---

Critical Issues

1. create-code-scanning-alert vs create-code-scanning-alerts — Singular/Plural Mismatch

Severity: High — could silently prevent struct-based deserialization

Layer	Field name
Schema (main_workflow_schema.json:6177)	create-code-scanning-alert (singular)
Raw map accessor (safe_outputs_config.go:161, create_code_scanning_alert.go:21)	create-code-scanning-alert (singular)
Go struct yaml tag (compiler_types.go:460)	create-code-scanning-alerts (plural)
Actual workflows (daily-semgrep-scan.md:15, daily-malicious-code-scan.md:17)	create-code-scanning-alert (singular)

The struct yaml tag create-code-scanning-alerts (plural) does not match the schema key or the actual workflow files which use the singular form. Struct-based YAML deserialization of a config using the singular key will silently fail to populate CreateCodeScanningAlerts. Only the raw-map accessor path (outputMap["create-code-scanning-alert"]) correctly handles the field.

Fix: Change compiler_types.go:460 yaml tag from create-code-scanning-alerts to create-code-scanning-alert, or make the raw-map parser populate the struct field explicitly.

---

Schema Description Inaccuracies

2. status-comment Auto-Enable Behavior Not Reflected in Schema or Docs

Severity: Medium — behavior surprise for users of slash_command / label_command

The schema description for activation.status-comment (main_workflow_schema.json:1888) states:

"When false or not specified, no status comments are posted. Must be explicitly set to true to enable status comments — there is no automatic bundling with ai-reaction."

docs/src/content/docs/reference/frontmatter.md:33 echoes this:

"must be explicitly set to true; not automatically enabled by reaction:"

However, compiler_safe_outputs.go:193–196 auto-enables status-comment: true for any workflow using slash_command or label_command triggers:

if (hasCommand || hasLabelCommand) && !hasStatusComment && workflowData.StatusComment == nil {
    trueVal := true
    workflowData.StatusComment = &trueVal
}

This behaviour was expanded in the current batch of changesets (minor-enable-reaction-status-comment-by-default) to also cover label_command.

Fix: Update schema description and frontmatter.md to read: "Defaults to true when slash_command or label_command triggers are used; must be explicitly set to true for other trigger types."

---

Documentation Gaps

3. NEW: sandbox.mcp.keepalive-interval Missing from frontmatter-full.md

Severity: Medium — introduced in commit c0865b8 (yesterday)

keepalive-interval was added to:

• Schema: main_workflow_schema.json:3234
• Go struct: tools_types.go:515 (yaml:"keepalive-interval,omitempty")
• Go extractor: frontmatter_extraction_security.go:500
• MCP gateway docs: docs/src/content/docs/reference/mcp-gateway.md:253 ✅

But not added to docs/src/content/docs/reference/frontmatter-full.md. The sandbox.mcp section there (around line 1711) documents mounts, env, port, api-key, and domain — but omits keepalive-interval.

Fix: Add keepalive-interval to the sandbox.mcp section in frontmatter-full.md.

4. sandbox.mcp Missing container, version, entrypoint, args, entrypointArgs from frontmatter-full.md

Severity: Low — pre-existing gap

Schema defines 11 properties for sandbox.mcp: container, version, entrypoint, args, entrypointArgs, mounts, env, port, api-key, domain, keepalive-interval.

frontmatter-full.md only documents 5 of them: mounts, env, port, api-key, domain. The container image fields (container, version, entrypoint, args, entrypointArgs) are undocumented in the frontmatter reference.

5. rate-limit Not Referenced in frontmatter.md

Severity: Low — discoverability issue

rate-limit is a top-level schema field (in main_workflow_schema.json) with full Go implementation (frontmatter_types.go:113, compiler.go:304). It is documented in docs/src/content/docs/reference/rate-limiting-controls.md:114, but not mentioned in docs/src/content/docs/reference/frontmatter.md. A user reading the frontmatter reference would not discover this field exists.

6. import-schema Not Documented in frontmatter.md

Severity: Low — discoverability issue

import-schema is a top-level schema field (main_workflow_schema.json) implemented in frontmatter_types.go:178 and expression_extraction.go:252. It is only shown in frontmatter-full.md. The main frontmatter.md reference has no section for it.

7. check-for-updates Not Documented in frontmatter.md

Severity: Low — broken reference link

Schema at line 8418 links to anchor https://github.github.com/gh-aw/reference/frontmatter/#check-for-updates which does not exist in frontmatter.md. Only appears in frontmatter-full.md:5982.

8. observability Not Documented in frontmatter.md

Severity: Low — pre-existing gap

observability is a top-level schema field (line 8316), implemented in compiler_yaml_ai_execution.go, present in frontmatter-full.md:5902, but entirely absent from frontmatter.md.

9. mark-pull-request-as-ready-for-review and set-issue-type Missing from safe-outputs.md

Severity: Low — pre-existing gap

Both fields are in the schema, implemented, and documented in frontmatter-full.md and glossary.md, but docs/src/content/docs/reference/safe-outputs.md has no section for either. Every other safe output has a dedicated section in that file.

---

Naming Inconsistencies

10. dispatch_repository Uses Underscore While All Peers Use Kebab-Case

Severity: Low — user-facing inconsistency

Schema key at line 7257 and the Go test file use dispatch_repository (underscore), while every other safe-outputs key uses kebab-case. The test confirms both dispatch_repository and dispatch-repository (dash) are accepted via aliasing, but the primary schema key uses underscore, creating inconsistency in the documentation and schema.

---

Recommendations

1. Immediately fix the create-code-scanning-alerts plural struct tag in compiler_types.go:460 — or add an explicit mapping from raw-map to the struct field to ensure consistency.
2. Update schema description for activation.status-comment to document the auto-enable behavior for slash_command/label_command triggers.
3. Add keepalive-interval to the sandbox.mcp section in frontmatter-full.md (regression from commit c0865b8).
4. Add missing sandbox.mcp container fields (container, version, entrypoint, args, entrypointArgs) to frontmatter-full.md.
5. Add a rate-limit: section to frontmatter.md with a cross-reference to rate-limiting-controls.md.
6. Add import-schema: and check-for-updates: sections to frontmatter.md.
7. Add mark-pull-request-as-ready-for-review and set-issue-type sections to safe-outputs.md.

---

Strategy Performance

Metric	Value
Strategy used	Cross-Layer Field Diff
Findings this run	10
New findings vs prior run	2 (keepalive-interval gap, status-comment schema inaccuracy clarified)
Effectiveness	High
Should reuse	Yes

References: §23933760200

AI generated by Schema Consistency Checker · history

• expires on Apr 4, 2026, 4:35 AM UTC

[github-actions[bot]]

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

A newer discussion is available at Discussion #24442.