[Schema Consistency] Schema Consistency Check — 2026-06-12

[github-actions[bot]]

Summary

• Inconsistencies Found: 1 actionable (new) + 1 standing low-priority
• Categories Analyzed: Schema ↔ Parser ↔ Documentation ↔ Workflows
• Strategy Used: S24 Parser key-alias vs schema enumeration check (new), supplemented by S19 Safe-output naming consistency and S7 Doc coverage audit
• Mode: proven-strategy (day-of-year mod 10 = 3) supplemented with a fresh alias-enumeration angle
• Overall health: Schema/parser/docs remain very consistent; the run surfaced one genuine alias gap previously not recorded in the strategy cache.

This run confirmed that the prior standing items (deprecation flags, IgnoredFrontmatterFields, role-matching semantics, enum/doc drift) all remain resolved. A fresh angle — enumerating every spelling the parser accepts and checking it against the schema's declared properties under additionalProperties: false — surfaced one real inconsistency.

Critical Issues

🔴 dispatch-repository (dash) alias is accepted by the parser & docs but rejected by the schema

The dispatch_repository safe-output parser intentionally accepts two spellings of the key:

• pkg/workflow/dispatch_repository.go:30 — comment: "Accepts both dispatch_repository (underscore, preferred) and dispatch-repository (dash, alias)."
• pkg/workflow/dispatch_repository.go:38-39 — falls back to outputMap["dispatch-repository"] when the underscore form is absent.
• pkg/workflow/dispatch_repository_test.go:93 — TestParseDispatchRepositoryConfig_DashAlias explicitly verifies the dash form works.
• .github/aw/safe-outputs-automation.md:97 — documents that both forms are accepted.

However, the JSON schema only declares the underscore property:

• pkg/parser/schemas/main_workflow_schema.json:9095 — "dispatch_repository" is the only key defined.
• safe-outputs.additionalProperties is false (verified via jq).

Impact: A user who follows the documented/tested dash alias (dispatch-repository:) gets a workflow that compiles fine but fails JSON-schema validation and receives no editor autocomplete / red squiggles under the dash form. The contract is internally inconsistent across the three sources of truth: parser says "valid", docs say "valid", schema says "invalid".

Verification evidence

$ grep -c '"dispatch-repository"' pkg/parser/schemas/main_workflow_schema.json
0
$ jq -r '.properties["safe-outputs"].additionalProperties' main_workflow_schema.json
false
$ grep -n 'dispatch-repository' pkg/workflow/dispatch_repository.go
30:// Accepts both "dispatch_repository" (underscore, preferred) and "dispatch-repository" (dash, alias).
39:		if configData, exists = outputMap["dispatch-repository"]; !exists {

Schema Improvements Needed

Pick one of two directions to restore consistency (recommend the first — it keeps the existing parser/test/doc contract intact):

1. Add the alias to the schema. Add a "dispatch-repository" property to safe-outputs.properties that mirrors ($ref or duplicates) the dispatch_repository sub-schema. This makes the documented dash form schema-valid and editor-friendly.
2. Drop the dash alias. Remove the outputMap["dispatch-repository"] fallback (dispatch_repository.go:38-39), delete TestParseDispatchRepositoryConfig_DashAlias, and remove the "accepts both" sentence from .github/aw/safe-outputs-automation.md:97. Then only dispatch_repository is accepted everywhere.

Documentation Gaps

None new. dispatch_repository is well documented (reference/safe-outputs.md:1331-1338, including the experimental-warning note). The only doc/parser/schema mismatch is the dash-alias issue above — whichever fix is chosen, safe-outputs-automation.md:97 should end up agreeing with the schema.

Standing Finding (low priority, re-confirmed)

⚪ dispatch_repository is the only snake_case key among ~75 safe-output keys

dispatch_repository (schema:9095) uses snake_case, while every sibling safe-output (e.g. dispatch-workflow at schema:9013, create-pull-request, add-comment, ...) uses kebab-case. Its child props (event_type, target_repo, allowed_repositories) are also snake_case. This is internally consistent (handler yaml tags + docs all use snake) and confirmed distinct from dispatch-workflow (two genuinely different features: repository_dispatch vs workflow_dispatch), so it's intentional but cosmetically off-convention. Resolving Schema-Improvement option 1 above would conveniently provide a convention-conforming dispatch-repository spelling as well.

Recommendations

1. Add dispatch-repository (kebab) as a schema property aliasing dispatch_repository — fixes the validation gap and offers a convention-conforming spelling in one change.
2. Add a small compiler/schema test asserting that every safe-output key the parser accepts is also a declared schema property (guards against future alias drift under additionalProperties: false).
3. Audit other parser "accepts both" alias chains the same way (generalized S24) — grep pkg/workflow/*.go for dual outputMap[...] lookups and "Accepts both"/"alias" comments.

Strategy Performance

Strategy	Findings	Effectiveness	Reuse
S24 Parser key-alias vs schema (new)	1 (critical)	High	Yes — generalize to all alias chains
S19 Safe-output naming consistency	1 (standing)	High	Yes
S7 Doc coverage audit	0	High	Periodic

Next Steps

• Add dispatch-repository alias property to main_workflow_schema.json (or remove the dash alias from parser/tests/docs)
• Add a test enforcing parser-accepted keys ⊆ schema properties for safe-outputs
• Generalize S24 across remaining parser alias fallback chains

References: §27399868814

Generated by ✅ Schema Consistency Checker · 122.8 AIC · ⌖ 25.7 AIC · ⊞ 9.5K · ◷

• expires on Jun 12, 2026, 11:01 PM UTC-08:00