APIMGMT-2097: updated linter to match new API versioning strategy

[ben-godin-sp]

I commented out the yearly-versioned checks in case we need to re-enable them in the next few days.

Manual Testing

I created some bad routes in sp-gateway-routes.yaml to generate these linter errors:

[github-actions]

Linting Report

Last updated: 6/17/2026, 10:07:07 AM

Found 21 total issues:

• ❌ Error: 21

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 Back Off Config Enabled Must Be Boolean (1)

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

  • Line 62: Invalid value for backOffConfig.enabled. Must be a boolean.

❌ Gateway Route Back Off Config Integer Fields Must Be Positive (2)

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

  • Line 63: Invalid value for backOffConfig integer field. Must be a positive integer.
  • Line 65: Invalid value for backOffConfig integer field. Must be a positive integer.

❌ Gateway Route Back Off Config Must Have Valid Properties (1)

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

  • Line 61: backOffConfig has an invalid field: unknownField

❌ Gateway Route Back Off Config Tiers Must Be Valid (1)

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

  • Line 64: Invalid value for backOffConfig.tiers. Must be an array of positive integers.

❌ Gateway Route Id And Path Must Have Matching Version (3)

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

  • Line 27: route id and path must contain the same API version (eg. example-route-id-v1, example/path/v1)
  • Line 36: route id and path must contain the same API version (eg. example-route-id-v1, example/path/v1)
  • Line 45: route id and path must contain the same API version (eg. example-route-id-v1, example/path/v1)

❌ Gateway Route Must Have Version In Id (1)

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

  • Line 36: route id must end with a version (eg. example-route-id-v1, example-route-id-internal)

❌ Gateway Route Path Must Start With Strip Prefix Path (1)

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

  • Line 45: stripPrefixPath must match path when stripPrefix is true