Skip to content

[plan] Refactor relationship prose to use dependencies keyword #7580

@github-actions

Description

@github-actions

Objective

Migrate field relationship descriptions from prose in description fields to JSON Schema's standard dependencies and dependentRequired keywords.

Context

Currently, all field relationships are described only in prose within description fields. This means schema validators can't automatically check relationships, and users relying on schema-driven tooling don't get validation errors for relationship violations.

Relationships to Migrate

Audit the schema for relationship prose in description fields and convert to JSON Schema standard keywords:

  1. dependencies - When field X requires field Y
  2. dependentRequired - When field X requires fields Y and Z
  3. dependentSchemas - When field X changes schema requirements

Example Migration

Before:

{
  "safe-outputs": {
    "description": "Configure safe outputs. Note: write permissions in strict mode require safe-outputs to be configured."
  }
}

After:

{
  "description": "Configure safe outputs.",
  "if": {
    "properties": { "strict": { "const": true } }
  },
  "then": {
    "if": {
      "properties": {
        "permissions": {
          "patternProperties": {
            ".*": { "enum": ["write"] }
          }
        }
      }
    },
    "then": {
      "required": ["safe-outputs"]
    }
  }
}

Approach

  1. Audit all description fields for relationship prose
  2. Create mapping of relationships to JSON Schema keywords
  3. Implement using dependencies, dependentRequired, or dependentSchemas
  4. Update description fields to remove redundant prose
  5. Add $comment for complex relationships needing explanation

Files to Modify

  • pkg/parser/schemas/frontmatter.json - Refactor all relationship prose
  • After changes, run make build to rebuild with embedded schema

Acceptance Criteria

  • All field relationships use JSON Schema standard keywords
  • No relationship information only in prose descriptions
  • Complex relationships have $comment explanations
  • Schema validators catch relationship violations
  • Existing valid configurations still pass validation
  • Documentation updated to reference relationship keywords

Testing

Test with JSON Schema validators that support dependencies to verify automatic relationship checking.
Related to #7575

AI generated by Plan Command for discussion #7569

Metadata

Metadata

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions