Fix type-checking rules to accept $ref as valid type specification

[Copilot]

Problem

Three Spectral rules were only checking for explicit type fields, ignoring that $ref provides stronger type information by referencing specific schema definitions. This is the correct and preferred way to specify complex types in OpenAPI 3.0.

Example that was incorrectly flagged:

subGoals:
  type: array
  items:
    $ref: '#/components/schemas/ExploreGoalsQueryResult'  # ← False positive warning
  nullable: true

Solution

Updated three related rules to accept either type or $ref as valid type specifications:

Before:

items-must-have-a-type:
  then:
    field: type
    function: truthy

After:

items-must-have-a-type:
  then:
    - function: truthy
    - function: schema
      functionOptions:
        schema:
          anyOf:
            - required: ["type"]
            - required: ["$ref"]

Changes

• Modified .workleap.rules.yaml to use JSON Schema validation with anyOf to accept both type and $ref fields for:
  • items-must-have-a-type - for array items
  • schemas-properties-must-have-a-type - for component schema properties
  • path-schema-properties-must-have-a-type - for path/response schema properties
• Added two-step validation: first ensures value is not null/empty, then validates type specification
• Updated rule descriptions to clarify that schema references are acceptable
• Added test cases to verify $ref validation:
  • TestSpecs/items-must-have-a-type-valid-ref.yaml
  • TestSpecs/schemas-properties-must-have-a-type-valid-ref.yaml
  • TestSpecs/path-schema-properties-must-have-a-type-valid-ref.yaml
• Updated test.ps1 to include the new tests (now 25 tests total)

Testing

✅ All 25 tests pass
✅ Valid items/properties with primitive types: type: string
✅ Valid items/properties with schema references: $ref: '#/components/schemas/MySchema'
✅ Valid items/properties with complex inline types
✅ Invalid items/properties (null/empty) still correctly flagged
✅ Backend and frontend configs work correctly

Impact

• Before: Valid OpenAPI specs using $ref for array items or properties could generate false positive warnings
• After: Both primitive types and schema references are correctly validated across all three rules
• Client generation: No impact - both approaches generate properly typed client code

This fix ensures consistency across all type-checking rules and aligns with OpenAPI 3.0 best practices where $ref is the standard approach for referencing complex schemas.

Fixes #41

Original prompt

---

This section details on the original issue you should resolve

<issue_title>items-must-have-a-type rule incorrectly flags $ref as missing type</issue_title>
<issue_description>## Problem Description

The items-must-have-a-type spectral rule is producing false positive warnings when array items use $ref to reference schema definitions instead of explicit primitive types.

Current Behavior

Warning triggered on:

subGoals:
  type: array
  items:
    $ref: '#/components/schemas/ExploreGoalsQueryResult'  # ← Warning here
  nullable: true

Rule Implementation (line 88-93 in .workleap.rules.yaml):

items-must-have-a-type:
  description: "All items must have a type. Refer to: https://gsoftdev.atlassian.net/wiki/spaces/TEC/pages/3858235678/IDP+OpenAPI+Rulesets#items-must-have-a-type"
  recommended: true
  severity: warn
  given: $.components.schemas..items
  then:
    field: type        # ← Only checks for 'type' field
    function: truthy   # ← Ignores '$ref' as valid typing

Root Cause

The current rule only validates the presence of a type field but doesn't recognize that $ref provides stronger type information by referencing a specific schema definition. According to OpenAPI 3.0 specification, using $ref is the correct and preferred way to reference complex types.

Expected Behavior

The rule should accept either:

• An explicit type field (for primitive types), OR
• A $ref field (for schema references)

Both provide type information and satisfy the rule's stated goal: "ensure that array objects must have a type".

Recommended Solution

Update the rule to accept either type or $ref as valid type specifications:

items-must-have-a-type:
  description: "All items must have a type or schema reference. Refer to: https://gsoftdev.atlassian.net/wiki/spaces/TEC/pages/3858235678/IDP+OpenAPI+Rulesets#items-must-have-a-type"
  recommended: true
  severity: warn
  given: $.components.schemas..items
  then:
    function: schema
    functionOptions:
      schema:
        anyOf:
          - required: ["type"]
          - required: ["$ref"]

Alternatively, using multiple conditions:

items-must-have-a-type:
  description: "All items must have a type or schema reference."
  recommended: true 
  severity: warn
  given: $.components.schemas..items
  then:
    - field: type
      function: truthy
    - field: $ref
      function: truthy
  # Should validate that at least one condition passes

Impact

• Current: Valid OpenAPI specs using $ref for array items generate false positive warnings
• After fix: Both primitive types and schema references will be correctly validated
• Client generation: No impact - both approaches generate properly typed client code

Example Valid Cases

# Should pass - primitive type
items:
  type: string

# Should pass - schema reference (currently fails)
items:
  $ref: '#/components/schemas/MySchema'

# Should fail - no type information
items:
  description: "No type specified"

Additional Context

This issue was discovered in the workleap-performance-management project where auto-generated OpenAPI specs correctly use $ref for complex array item types, but trigger this validation warning.

The $ref approach provides better type safety than generic primitive types and is the standard practice for referencing complex schemas in OpenAPI specifications.
</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #41

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull Request Overview

This PR fixes the items-must-have-a-type Spectral rule to correctly accept $ref as a valid type specification for array items, eliminating false positive warnings when schemas reference complex types using $ref instead of primitive types.

Key Changes:

• Updated the rule to validate using JSON Schema with anyOf to accept either type or $ref fields
• Added test case to verify $ref validation works correctly
• Updated rule description to clarify that schema references are acceptable

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
.workleap.rules.yaml	Modified the items-must-have-a-type rule to accept both type and $ref using JSON Schema validation with anyOf
TestSpecs/items-must-have-a-type-valid-ref.yaml	Added test spec demonstrating valid array items using $ref to reference schema definitions
test.ps1	Added new test case entry for validating $ref support in array items

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[jcbuteau]

I think schemas-properties-must-have-a-type also has the same issue

[salliegsoft]

I think schemas-properties-must-have-a-type also has the same issue

@copilot Can you look into this

[Copilot]

I think schemas-properties-must-have-a-type also has the same issue

@copilot Can you look into this

Fixed in commit 55311cd. Updated both schemas-properties-must-have-a-type and path-schema-properties-must-have-a-type rules to accept $ref as valid type specification, matching the pattern used for items-must-have-a-type. All 25 tests pass.