Skip to content

[Code Quality] Clarify safe-jobs field in schema and documentation #11265

Closed as not planned

Description

@github-actions

Description

The safe-jobs field is accessed in compiler code (pkg/workflow/safe_jobs.go, compiler_orchestrator.go, compiler_safe_output_jobs.go) but is NOT defined in main_workflow_schema.json. Additionally, documentation is unclear whether this is user-facing or internal-only.

Background

Identified during the Schema Consistency Analysis on 2026-01-21. Analysis revealed:

  • Used in code: 3 files access frontmatter["safe-jobs"]
  • Schema status: NOT in main_workflow_schema.json (0 of 38 top-level properties)
  • Documentation gap: Mentioned in compilation-process.md but not in frontmatter.md

Code comment from safe_jobs.go:38:

"User workflows should use 'safe-outputs.jobs' syntax; the top-level 'safe-jobs' key is NOT supported."

Contradiction: Code accesses safe-jobs despite comment saying it's not supported.

Impact

  • Schema validation cannot catch invalid safe-jobs configurations
  • No type checking or structure enforcement
  • Developers confused about whether to use safe-jobs or safe-outputs.jobs
  • Potential for malformed data causing runtime errors
  • Documentation inconsistency

Suggested Changes

Option A: Make it User-Facing (if intentional)

  1. Add to schema (pkg/parser/schemas/main_workflow_schema.json):

    {
      "safe-jobs": {
        "type": "object",
        "description": "Custom safe output jobs with specialized logic",
        "additionalProperties": {
          "type": "object",
          "properties": {
            "steps": { "type": "array" },
            "outputs": { "type": "object" }
          }
        }
      }
    }
  2. Document in frontmatter reference (docs/src/content/docs/reference/frontmatter.md):

    • Add safe-jobs section
    • Explain difference from safe-outputs.jobs
    • Provide examples
  3. Update code comment in safe_jobs.go:38 to reflect support

Option B: Keep it Internal-Only (if intentional)

  1. Document as internal: Add clear comment in code explaining this is compiler-internal
  2. Remove public mention: Delete reference from compilation-process.md:270
  3. Add schema note: Document in schema comments that safe-jobs is reserved for internal use

Option C: Remove if Unused (if deprecated)

  1. Remove code access: Delete frontmatter["safe-jobs"] accesses
  2. Update schema: Add to deprecated/removed fields list
  3. Migration guide: If users have safe-jobs, show how to migrate to safe-outputs.jobs

Files Affected

Code:

  • pkg/workflow/safe_jobs.go (line 40)
  • pkg/workflow/compiler_orchestrator.go (line 744)
  • pkg/workflow/compiler_safe_output_jobs.go (lines 55-60)

Schema:

  • pkg/parser/schemas/main_workflow_schema.json (add definition)

Documentation:

  • docs/src/content/docs/reference/frontmatter.md (document or clarify)
  • docs/src/content/docs/reference/compilation-process.md (line 270, update or remove)

Success Criteria

  • Schema either includes safe-jobs with validation OR documents it as internal-only
  • Documentation consistent with implementation
  • Code comments align with actual usage
  • No ambiguity for users about which field to use
  • Schema validation catches configuration errors

Priority

MEDIUM - Affects schema validation and developer clarity

Estimated effort: 2-4 hours (depending on chosen option)

Source

Extracted from Schema Consistency Analysis discussion #11121

Analysis quote:

"🔴 Issue #2: safe-jobs Field Missing from Schema
Problem: The safe-jobs top-level field is accessed in compiler code but NOT defined in main_workflow_schema.json.
Impact: Schema validation cannot catch invalid safe-jobs configurations, no type checking or structure enforcement, potential for malformed data causing runtime errors"

AI generated by Discussion Task Miner - Code Quality Improvement Agent

  • expires on Feb 5, 2026, 12:26 PM UTC

Activity

  1. github-actions commented on Jan 23, 2026

    @github-actions
    ContributorAuthor

    🍪 Issue Monster has assigned this to Copilot!

    I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

    The Copilot agent will analyze the issue and create a pull request with the fix.

    Om nom nom! 🍪

    AI generated by Issue Monster

  2. github-actions commented on Jan 24, 2026

    @github-actions
    ContributorAuthor

    🍪 Issue Monster has assigned this to Copilot!

    I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

    The Copilot agent will analyze the issue and create a pull request with the fix.

    Om nom nom! 🍪

    AI generated by Issue Monster

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions