APIMGMT-1888: Add new rule to validate versionDetailsMap keys against versionEnd

[victor-mancera-sp]

Adds a Spectral rule for gateway route specs so that versionDetailsMap does not contain yearly API version keys (v20XX) above versionEnd. Entries whose version is greater than versionEnd are ignored by sp-gateway, so this catches silent misconfiguration in sp-gateway-routes.yaml (and related files) at lint time.

spectral lint on a gateway YAML using gateway-ruleset.yaml completes successfully against the current sp-gateway-routes.yaml in consuming repos (no new violations for valid configs). Then, I modified the test YAML file to include an entry that would result in a violation, obtaining the following result:

victor.mancera@vmancera-09DKQ9N api-linter % cd /Users/victor.mancera/code/api-linter
npx @stoplight/spectral-cli lint packages/test-files/sp-gateway-routes.yaml --ruleset packages/gateway-rulesets/gateway-ruleset.yaml
'fs' is imported by packages/gateway-rulesets/functions/check-path-documentation.js, but could not be resolved – treating it as an external dependency
'path' is imported by packages/gateway-rulesets/functions/check-path-documentation.js, but could not be resolved – treating it as an external dependency

/Users/victor.mancera/code/api-linter/packages/test-files/sp-gateway-routes.yaml
 37:7  error  gateway-route-version-details-map-keys-must-not-exceed-version-end  versionDetailsMap key "v2028" (API version 2028) cannot be greater than versionEnd (2026); that entry is ignored by sp-gateway.  sp-gateway.routes[2]

[github-actions]

Linting Report

Last updated: 4/7/2026, 2:42:17 PM

Found 12 total issues:

• ❌ Error: 12

OpenAPI Specs

❌ Invalid Ref (8)

• File: /packages/test-files/sailpoint-api.OpenAPI.yaml (7)

  • Line 86: #/ é, à, ö,/schemas/Pet does not exist
  • Line 100: #/components/schemas/ é, à, ö, does not exist
  • Line 138: #/components/ é, à, ö,/Pet does not exist
  • Line 314: #/components/ é, à, ö,/ApiResponse does not exist
  • Line 349: #/Test/schemas/Order does not exist
  • Line 352: #/components/Test/Order does not exist
  • Line 355: #/components/schemas/Test does not exist

• File: /packages/test-files/v2024/paths/account.yaml (1)

  • Line 32: ENOENT: no such file or directory, open /home/runner/work/api-linter/api-linter/packages/test-files/v2024/responses/InvalidReference.yaml

❌ Paths Must Not Reference Documents Outside Of Their Version (2)

• File: /packages/test-files/v2024/paths/account.yaml (2)

  • Line 28: Rule 405: Referenced document beta/schemas/Account.yaml is outside the allowed version folder v2024: https://sailpoint-oss.github.io/sailpoint-api-guidelines/#405
  • Line 66: Rule 405: Referenced document beta/schemas/BaseCommonDto.yaml is outside the allowed version folder v2024: https://sailpoint-oss.github.io/sailpoint-api-guidelines/#405

❌ Root Tags Must Be In Alphabetical Order (1)

• File: /packages/test-files/sailpoint-api.OpenAPI.yaml (1)

  • Line 23: Rule 403: Tags must be in alphabetical order: https://sailpoint-oss.github.io/sailpoint-api-guidelines/#403

Gateway

❌ Gateway Route Version Details Map Keys Must Not Exceed Version End (1)

• File: /packages/test-files/sp-gateway-routes.yaml (1)

  • Line 37: versionDetailsMap key "v2028" (API version 2028) cannot be greater than versionEnd (2026); that entry is ignored by sp-gateway.

[lori-vangulick-sp]

So, will this message include the variables from the route? Will this appear in the linter report?
Or will the user only see generic message "versionDetailsMap keys for yearly API versions (v20XX) must not be greater than versionEnd, or sp-gateway will ignore them"?

I think specific message is better, but I don't see that in your pr example.