[Schema Consistency] Schema Consistency Check — 2026-05-29

[github-actions[bot]]

Summary

• Inconsistencies found: 10 (7 re-confirmed from prior runs + 3 new this run)
• Areas analyzed: Schema ↔ Parser, Schema ↔ Docs, Schema ↔ Workflows, Parser ↔ Docs
• Strategy mode: NEW approach (day-of-year 149 mod 10 = 9 → 30% branch)
• New strategy: strategy-18 — additionalProperties:false consistency on object subschemas
• Status: ⚠️ Recurring findings from 2026-05-27/28 still unfixed on main (f3e4f74)

Critical Issues

1. ⚠️ Schema silently accepts typos in workflow_call / dispatch_repository input definitions (NEW)

Three user-input subschemas in pkg/parser/schemas/main_workflow_schema.json declare properties but omit additionalProperties: false, so typos pass validation silently:

Subschema path	Defined keys
properties.on.oneOf[1].properties.workflow_call.oneOf[1].properties.inputs.additionalProperties	type, description, required, default
properties.on.oneOf[1].properties.workflow_call.oneOf[1].properties.secrets.additionalProperties	description, required
properties["safe-outputs"].properties.dispatch_repository.additionalProperties.properties.inputs.additionalProperties	type, description, options, required, default

The sibling input def under safe-outputs.actions.*.inputs.* does set additionalProperties: false, making the inconsistency a clear oversight. Fix: add "additionalProperties": false to each.

2. ⚠️ Legacy rate-limit field has NO user-visible deprecation warning

pkg/workflow/role_checks.go:301 only emits roleLog.Print("Extracted legacy rate-limit configuration") (debug-level, hidden from users). compiler_validators.go:344 emits an experimental warning for the new user-rate-limit key but nothing for the legacy alias, even though the schema description says "Legacy alias for 'user-rate-limit'. Prefer ...". Fix: replace the debug log with a user-facing compile warning.

Documentation Gaps

3. Three top-level schema fields have ZERO curated docs

check-for-updates, disable-model-invocation, run-install-scripts appear only in the auto-generated docs/src/content/docs/reference/frontmatter-full.md. No curated page references them.

4. Schema descriptions link to non-existent doc anchors

Schema descriptions for check-for-updates and run-install-scripts end with See: .../reference/frontmatter/#check-for-updates and .../#run-install-scripts. Neither anchor heading exists in docs/src/content/docs/reference/frontmatter.md. Fix: add the headings or drop the dead See: links.

5. IgnoredFrontmatterFields (user-invokable) is undocumented

pkg/constants/constants.go:309 ships IgnoredFrontmatterFields = []string{"user-invokable"} as a Copilot custom-agent interop hint (comment at line 308). The name appears nowhere in docs/, the schema, or any workflow file. Users have no way to discover this escape hatch.

6. applyTo accepted by parser but undocumented and falsely claimed to be schema-validated

• pkg/parser/include_processor.go:267 keeps "applyTo": true in validFields.
• pkg/parser/schema_utilities.go:14 comment says "all previously ignored fields (description, applyTo) are now validated by the schema" — but applyTo is not a property in main_workflow_schema.json, and grep -rn applyTo docs/src/content/docs/ returns zero hits.

Fix: either add applyTo as a real schema property + document it, or remove the stale comment and the validFields entry.

Schema Improvements Needed

7. Deprecated/legacy fields lack the JSON Schema deprecated: true flag

Verified via jq:

Field	Description starts with	deprecated	x-deprecation-message
inline-sub-agents	"Deprecated switch for inline sub-agent support..."	null	null
rate-limit	"Legacy alias for 'user-rate-limit'..."	null	null

IDE hovers and validators that surface JSON Schema 2019-09+ deprecated cannot detect either. Fix: add "deprecated": true and "x-deprecation-message" to both.

8. $defs.templatable_integer is defined but never $ref'd

main_workflow_schema.json:10438 defines templatable_integer; no $ref in the file points to it. Sibling $defs.templatable_boolean is referenced 5+ times. Several integer fields (max-runs, max-effective-tokens, timeout-minutes) inline duplicate oneOf patterns that the dead $defs entry was presumably meant to centralize. Fix: delete the def or wire it up.

9. engine.id lists valid values in prose only — no JSON Schema enum

engine.id declares type: string with valid values in the description only (no enum). The compiler additionally handles a custom id that is not in the prose enumeration. Fix: add an enum constraint.

Parser Updates Required

10. SharedWorkflowForbiddenFields contains dead entries command and roles

pkg/constants/constants.go:328 lists "command" and line 336 lists "roles". Neither is a top-level property in the schema (jq -r '.properties | keys[] | select(test("role|command"; "i"))' → empty). Because the top-level schema is additionalProperties: false, any top-level use of command: / roles: is already rejected by schema validation — these are dead allowlist entries. Fix: delete both entries (or comment why they're reserved).

Workflow Violations

No systematic violations detected. field_gaps.in_used_not_schema is noisy because nested keys are flattened (model, task, verdict, etc. live deep inside safe-outputs.*/experiments.* subtrees); spot-checks of the suspicious entries did not reveal real top-level schema violations.

Recommendations (priority order)

1. Add additionalProperties: false to the three subschemas in finding rejig docs #1 — ~6 lines of JSON, prevents typo traps.
2. Emit user-visible deprecation warning for legacy rate-limit (finding Add workflow: githubnext/agentics/weekly-research #2) — small parser change, prevents silent migration breakage.
3. Reconcile schema↔docs anchors (finding Add workflow: githubnext/agentics/weekly-research #4) — add the headings or drop the dead See: links.
4. Add deprecated: true to inline-sub-agents and rate-limit (finding Weekly Research Report: AI Workflow Automation Landscape and Market Opportunities - August 2025 #7).
5. Decide on applyTo (finding add cli flag to guard dropping a agentic workflow instructinos file #6) — promote to real schema field or remove.
6. Delete dead command/roles entries from SharedWorkflowForbiddenFields (finding Remove ai-inference, opencode, genaiscript agentic engines for now #10) and resolve templatable_integer (finding Add workflow: githubnext/agentics/weekly-research #8).

Strategy Performance

• strategy-18 (NEW): 3 high-confidence findings on first run → high effectiveness, cached for re-use.
• Re-confirmed: strategy-7, strategy-8, strategy-9, strategy-10, strategy-12, strategy-13, strategy-16, strategy-17 — all still firing because last week's findings haven't merged.
• Should reuse: YES.

Next Steps

• Schema: add additionalProperties: false to workflow_call/dispatch_repository input/secret subschemas
• Schema: add deprecated: true + x-deprecation-message to inline-sub-agents and rate-limit
• Schema: delete or wire up $defs.templatable_integer
• Schema: add enum constraint to engine.id
• Parser: emit user-visible deprecation warning at pkg/workflow/role_checks.go:301
• Parser: delete command/roles from SharedWorkflowForbiddenFields (pkg/constants/constants.go:328,336)
• Docs: add sections for check-for-updates, disable-model-invocation, run-install-scripts to reference/frontmatter.md (or drop dead See: links)
• Docs: document the user-invokable escape hatch for Copilot interop
• Docs: document or remove applyTo; fix stale comment in pkg/parser/schema_utilities.go:14

References:

• Workflow run: §26622380936
• HEAD: f3e4f74 (docs: Measuring Impact docs: Measuring Impact #35651)
• Prior runs: 2026-05-27, 2026-05-28 (findings re-confirmed unfixed)

Generated by ✅ Schema Consistency Checker · opus47 8.3M · ◷

• expires on May 30, 2026, 6:48 AM UTC

[github-actions[bot]]

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

A newer discussion is available at Discussion #35882.