[Schema Consistency] Schema Consistency Check - 2026-04-10

[github-actions[bot]]

Summary

• Inconsistencies Found: 6 new findings (2 docs gaps + 2 constraint gaps), plus 5 confirmed persistent issues
• Categories Analyzed: Schema ↔ Parser, Schema ↔ Documentation, Schema ↔ Workflows
• Strategy Used: Cross-Layer Field Diff (proven, success_count=10)
• New Findings: Yes — pre-steps/run-install-scripts absent from frontmatter-full.md; upload-artifact constraint gaps

---

Critical Issues

CONSTRAINT GAP: upload-artifact.max-uploads maximum not enforced

• Schema: max-uploads has maximum: 20
• Go: publish_artifacts.go:81 only checks v > 0, never v <= 20
• Impact: A workflow setting max-uploads: 999 silently accepts any value without error
• File: pkg/workflow/publish_artifacts.go:81

CONSTRAINT GAP: upload-artifact.defaults.if-no-files enum not validated

• Schema: if-no-files has enum: ["error", "ignore"]
• Go: publish_artifacts.go:152–153 accepts any non-empty string
• Impact: Invalid values like if-no-files: warn pass compilation but will fail at runtime in the safe-outputs handler
• File: pkg/workflow/publish_artifacts.go:152–153

---

Documentation Gaps

NEW: pre-steps absent from frontmatter-full.md

• Schema: Full definition at pkg/parser/schemas/main_workflow_schema.json with detailed description about minting short-lived tokens before checkout
• Docs: Not present in frontmatter.md OR frontmatter-full.md; only mentioned incidentally in imports.md and dependencies.md
• Impact: Users cannot discover this feature through the reference docs

NEW: run-install-scripts absent from frontmatter-full.md

• Schema: Boolean field default: false with supply-chain security warning description
• Docs: Not present in frontmatter.md OR frontmatter-full.md
• Implementation: pkg/workflow/run_install_scripts_validation.go (per-runtime and global)
• Impact: Security-sensitive feature with no user-facing documentation

---

Persistent Issues (Unresolved)

View persistent documentation gaps

1. observability.otlp sub-fields undocumented

• frontmatter-full.md shows only observability: {} with no sub-fields
• Schema defines otlp.endpoint (OTLP collector URL, auto-allowlisted in firewall) and otlp.headers (injected as OTEL_EXPORTER_OTLP_HEADERS)
• First noted: 2026-04-07

2. keepalive-interval in sandbox.mcp undocumented

• Schema: pkg/parser/schemas/main_workflow_schema.json:3234 defines keepalive ping interval for HTTP MCP backends
• Docs: Not in frontmatter-full.md sandbox.mcp section
• First noted: 2026-04-07

3. 30 safe-outputs tools missing from frontmatter-full.md

The safe-outputs: section in frontmatter-full.md is missing 30 tool entries. Notable gap: upload-artifact (newly added tool with max-uploads, retention-days, skip-archive, max-size-bytes, allowed-paths, filters, defaults sub-fields).

Other missing tools: actions, activation-comments, call-workflow, concurrency-group, dispatch-workflow, dispatch_repository, env, environment, failure-issue-repo, github-app, group-reports, hide-comment, id-token, jobs, max-bot-mentions, max-patch-size, missing-data, missing-tool, noop, push-to-pull-request-branch, report-failure-as-issue, report-incomplete, runs-on, scripts, set-issue-type, steps, threat-detection, update-release, upload-asset

4. 12 schema fields missing from frontmatter.md

check-for-updates, disable-model-invocation, import-schema, infer, inlined-imports, mcp-servers, observability, pre-steps, rate-limit, run-install-scripts, secret-masking, tracker-id

Note: run-install-scripts is newly added to this list (up from 11 in previous run).

5. Feature flags undocumented

cli-proxy, cli-proxy-writable, copilot-requests, mcp-gateway, disable-xpia-prompt, mcp-scripts are used in production workflows but absent from frontmatter.md and frontmatter-full.md.

View previously resolved findings

RESOLVED: proxy-args now in schema

$defs.stdio_mcp_tool.properties now includes proxy-args — the schema and Go validation are consistent. Previously a workflow using proxy-args would fail schema validation but pass Go validation.

RESOLVED: status-comment auto-enable behavior documented

frontmatter.md:33 correctly states automatic enablement for slash_command and label_command triggers.

---

Recommendations

1. Fix upload-artifact constraint gaps — Add v <= 20 guard for max-uploads in publish_artifacts.go:81 and add enum validation for if-no-files at publish_artifacts.go:152. These are cheap one-line fixes consistent with how other constraint gaps were closed (e.g. max-patch-size).

2. Document pre-steps in frontmatter-full.md — The feature is fully implemented with a rich schema description (short-lived token minting, step output references). Add a dedicated YAML example block to both frontmatter.md and frontmatter-full.md.

3. Document run-install-scripts in frontmatter-full.md — Security-sensitive field with no user-facing reference. Add to frontmatter-full.md alongside a security note (supply chain warning, per-runtime alternative via runtimes.node.run-install-scripts).

4. Document upload-artifact safe-outputs tool — Newly active feature (used in daily-performance-summary workflow). Add its sub-fields (max-uploads, retention-days, skip-archive, max-size-bytes, allowed-paths, filters, defaults) to frontmatter-full.md.

5. Expand observability.otlp docs — Add endpoint and headers sub-field examples to frontmatter-full.md; the schema descriptions are already accurate.

---

Strategy Performance

• Strategy Used: Cross-Layer Field Diff
• Findings: 4 new + 5 persistent confirmed = 9 total
• Effectiveness: HIGH
• Should Reuse: YES

---

Next Steps

• pkg/workflow/publish_artifacts.go:81 — add v <= 20 guard for max-uploads
• pkg/workflow/publish_artifacts.go:152 — add if-no-files enum check
• docs/src/content/docs/reference/frontmatter-full.md — add pre-steps: example block
• docs/src/content/docs/reference/frontmatter-full.md — add run-install-scripts: example block
• docs/src/content/docs/reference/frontmatter-full.md — add upload-artifact: safe-outputs tool block
• docs/src/content/docs/reference/frontmatter-full.md — expand observability: block with otlp: sub-fields

References:

• §24226522306

Generated by Schema Consistency Checker · ● 235.2K · ◷

• expires on Apr 11, 2026, 4:40 AM UTC

[github-actions[bot]]

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

A newer discussion is available at Discussion #25753.