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

[github-actions[bot]]

Schema consistency analysis across four layers: main_workflow_schema.json, parser/compiler Go structs (pkg/workflow/*.go), documentation (docs/src/content/docs/reference/), and actual workflows (.github/workflows/*.md).

Strategy used: Cross-Layer Field Diff (proven, day-of-year 90 % 10 = 0 → reuse strategy)
Run: §23780462593

---

Summary

Category	Findings
Schema ↔ Parser/Struct mismatches	6
Schema ↔ Documentation gaps	2
Convention inconsistencies	2
Total	10

---

Critical Issues

1. version and include fields in FrontmatterConfig but absent from schema

FrontmatterConfig (pkg/workflow/frontmatter_types.go:134,179) defines:

Version string `json:"version,omitempty"`
Include any    `json:"include,omitempty"`

The top-level schema (pkg/parser/schemas/main_workflow_schema.json) sets "additionalProperties": false and does not include version or include as properties. With schema validation enabled (skipValidation: false), any workflow using these fields would fail validation. Validation is currently skipped by default (skipValidation: true in compiler_types.go:159), masking the issue.

Impact: High — if validation is ever enabled globally, existing workflows using version: or include: at the top level will break.
Recommendation: Either add version and include to the schema, or remove them from FrontmatterConfig.

---

2. copilot-requests permission: implemented in parser but missing from schema

permissions.go:156 defines:

PermissionCopilotRequests PermissionScope = "copilot-requests"

and permissions.go:47 handles it in convertStringToPermissionScope. However, copilot-requests is not listed under $defs.github_actions_permissions.properties in the schema.

Impact: Medium — schema validation would reject permissions: { copilot-requests: write } even though the parser handles it correctly. Also, IDE/editor autocompletion powered by the schema would not suggest this permission.
Recommendation: Add copilot-requests to $defs.github_actions_permissions.properties in the schema.

---

3. GitHubActionsPermissionsConfig struct missing newer GITHUB_TOKEN scopes

Schema $defs.github_actions_permissions.properties includes attestations, metadata, models, and all. These are not in GitHubActionsPermissionsConfig (frontmatter_types.go:40–54):

Scope	In schema	In struct	In PermissionScope constants
attestations	✅	❌	✅
metadata	✅	❌	✅
models	✅	❌	✅
all	✅	❌	handled in parsePermissionsConfig

Since permissions are processed via NewPermissionsParser(data.Permissions) using the raw YAML string, there is no functional breakage. However, parsePermissionsConfig (frontmatter_types.go:342) lacks case branches for these scopes, meaning PermissionsTyped will silently drop them on round-trip via ToMap().

Recommendation: Add these scopes to GitHubActionsPermissionsConfig and parsePermissionsConfig.

---

4. create-code-scanning-alert naming: singular in schema/parser, plural in struct yaml tag

Schema key: create-code-scanning-alert (singular)
Parser reads: outputMap["create-code-scanning-alert"] (create_code_scanning_alert.go:38)
Struct yaml tag: yaml:"create-code-scanning-alerts,omitempty" (plural, compiler_types.go:463)

The struct uses create-code-scanning-alerts (plural) for its yaml tag, while the schema and parser use create-code-scanning-alert (singular). Since parsing is done via direct map access (not yaml unmarshaling), there is no runtime breakage. However, if SafeOutputsConfig were ever serialized to YAML and parsed back, the key name would be wrong.

Recommendation: Align the struct yaml tag to yaml:"create-code-scanning-alert,omitempty" (singular).

---

Documentation Gaps

5. activation-comments placement: top-level in schema vs nested in struct

The schema places activation-comments at safe-outputs.activation-comments (top-level). The struct stores it as SafeOutputMessagesConfig.ActivationComments (nested under messages). Crucially, the schema's messages block does not include activation-comments in its properties (additionalProperties: false).

This creates a confusing situation:

• Writing safe-outputs.activation-comments: false ✅ (works in parser, validated by schema)
• Writing safe-outputs.messages.activation-comments: false ✅ (works via struct yaml tag) but ❌ (schema rejects it — messages.additionalProperties: false)

Recommendation: Either add activation-comments to the schema's messages properties, or clarify in docs that it must only be used at the safe-outputs top level (not under messages).

---

6. FirewallConfig yaml tags use snake_case; schema and docs use kebab-case

FirewallConfig (firewall.go:19–21) defines:

LogLevel  string   `yaml:"log_level,omitempty"`
SSLBump   bool     `yaml:"ssl_bump,omitempty"`
AllowURLs []string `yaml:"allow_urls,omitempty"`

Schema (main_workflow_schema.json) uses: log-level, ssl-bump, allow-urls (kebab-case)
Docs (docs/src/content/docs/reference/network.md:219,234,235) use: log-level, ssl-bump, allow-urls

Parsing is done manually in frontmatter_extraction_security.go:145–163 using the kebab-case keys, so there is no functional issue. However, the struct yaml tags are misleading — they do not match what the YAML parser would expect if the struct were ever used with yaml.Unmarshal directly.

Recommendation: Update struct yaml tags to use kebab-case to match schema/docs convention:

LogLevel  string   `yaml:"log-level,omitempty"`
SSLBump   bool     `yaml:"ssl-bump,omitempty"`
AllowURLs []string `yaml:"allow-urls,omitempty"`

---

Convention Inconsistencies

7. dispatch_repository uses underscore while all other safe-outputs keys use kebab-case

In SafeOutputsConfig (compiler_types.go:485):

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

Schema: dispatch_repository (underscore)
All other safe-outputs keys: kebab-case

The parser explicitly accepts both dispatch_repository and dispatch-repository (dispatch_repository.go:38–39). This was likely intentional (matching the GitHub Actions event type repository_dispatch), but creates a convention inconsistency.

Recommendation: Document this explicitly in the schema description and docs. Consider whether to make dispatch-repository the primary key and dispatch_repository an alias, or vice versa.

---

8. runtimesConfigToMap drops action-repo and action-version on round-trip

RuntimeConfig (frontmatter_types.go:14–19) has ActionRepo and ActionVersion fields. parseRuntimesConfig (frontmatter_types.go:299–308) correctly reads them. However, runtimesConfigToMap (frontmatter_types.go:676–761) only serializes version and if, silently dropping action-repo and action-version.

Since the compiler uses the raw Runtimes map[string]any (not RuntimesTyped) for actual YAML generation, there is no functional breakage. But the typed struct has a lossy round-trip.

Recommendation: Add action-repo and action-version serialization to runtimesConfigToMap.

---

Schema Improvements Needed

9. bots top-level schema property vs compiler reading on.bots

The schema defines bots as both:

1. A top-level frontmatter property (properties.bots) — describes a bot allowlist
2. A nested property under on trigger configuration

The compiler (role_checks.go:143–159) exclusively reads on.bots. A top-level bots: field would pass schema validation but be silently ignored by the compiler.

Recommendation: Remove the top-level bots schema property, or make the compiler also check frontmatter["bots"].

---

10. env field type mismatch: schema allows string | object, struct only handles object

Schema (properties.env.oneOf): allows either object (map of string→string) or plain string
FrontmatterConfig.Env (frontmatter_types.go:162): map[string]string (object only)

If a user writes env: "some-value", schema validation would pass, but JSON unmarshaling into FrontmatterConfig would fail silently (the field would be empty).

Recommendation: Either remove the string variant from the env schema oneOf, or update the struct to handle the string case.

---

Schema Fields Not Used in Any Current Workflow

The following schema fields exist and are handled by the parser, but are not used in any .github/workflows/*.md file in this repository. They may need documentation or example workflows:

bots, check-for-updates, command, container, dependencies, disable-model-invocation, environment, github-app, import-schema, infer, labels, mcp-scripts, mcp-servers, metadata, observability, post-steps, private, resources, run-name, runs-on-slim, secret-masking, secrets, services

Deprecated/Removed Schema Fields

• tools.grep: Marked deprecated: true in schema — now a no-op (grep is part of default bash tools). Not handled as a struct field; falls into ToolsConfig.Custom map.
• tools.serena: Marked deprecated: true, x-removed: true — built-in support removed. Users should import shared/mcp/serena.md.
• safe-outputs.create-agent-task: Deprecated alias for create-agent-session. Parser emits a warning and redirects to create-agent-session.
• network.firewall: Marked deprecated: true — firewall is now always enabled. Use sandbox.agent instead.

---

Recommendations (Prioritized)

1. Enable schema validation gradually — Address version and include missing from schema first, then enable validation.
2. Add copilot-requests to schema — One-line addition to github_actions_permissions.properties.
3. Fix create-code-scanning-alerts yaml tag — Change to singular to match schema.
4. Update GitHubActionsPermissionsConfig — Add attestations, metadata, models fields.
5. Align FirewallConfig yaml tags — Switch to kebab-case.
6. Clarify activation-comments placement — Update schema or docs to remove ambiguity.
7. Fix runtimesConfigToMap — Include action-repo and action-version.
8. Remove top-level bots from schema (or handle it in compiler).

---

Strategy Performance

• Strategy Used: Cross-Layer Field Diff
• Findings: 10
• Effectiveness: HIGH
• Should Reuse: YES

References:

• §23780462593

AI generated by Schema Consistency Checker · history

• expires on Apr 1, 2026, 4:41 AM UTC

[github-actions[bot]]

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

A newer discussion is available at Discussion #23823.