This pull request prepares the gateway to support a non-destructive, automated migration of Protected Resource Metadata (PRM) configuration. It accomplishes this by formally deprecating the legacy top-level PRM structure and adding a suite of tests to guarantee specific runtime behaviors, ensuring a safe transition for users upgrading and the ability to downgrade without data loss.

Files Changed Analysis

The changes are focused entirely on API definitions and testing, with no modifications to the core runtime logic:

• API Schemas (apidef/{mcp,oas,streams}/schema/*.json): All four x-tyk-api-gateway.json schema variants have been updated. The legacy X-Tyk-ProtectedResourceMetadata type is now marked with "deprecated": true and includes a description pointing to the new location. This provides a clear signal for deprecation to UIs and other schema-aware tools.
• Go Definitions (apidef/oas/authentication.go): The legacy ProtectedResourceMetadata struct and its corresponding field on the Authentication struct are now marked with // Deprecated: comments. This will trigger warnings in IDEs and static analysis tools, guiding developers to use the new structure.
• Testing (apidef/oas/authentication_test.go, gateway/mw_protected_resource_oauth2_test.go): The majority of the changes consist of new tests that codify and lock in existing behavior. These tests verify:
  1. The deprecation flag is correctly set in all JSON schemas.
  2. Both legacy and new PRM blocks can coexist and round-trip through JSON serialization without side effects.
  3. PRM continues to be served even when the main OAuth2 authentication is disabled.
  4. The gateway correctly falls back to the legacy PRM block if the new per-scheme block is absent.

Architecture & Impact Assessment

• What this PR accomplishes: It ensures the gateway can safely handle API definitions that have been auto-migrated by the Tyk Dashboard. By deprecating the old structure and guaranteeing fallback behavior, it provides both forward and backward compatibility, which is critical for a smooth user experience during upgrades and potential downgrades.

• Key technical changes introduced:

  1. Formal Deprecation: The legacy top-level PRM configuration is officially marked as deprecated in both the Go code (// Deprecated:) and the JSON schemas ("deprecated": true).
  2. Behavioral Guarantees via Tests: New tests are added to prevent future regressions by codifying existing gateway behaviors that the migration strategy relies upon.

• Affected system components:

  • API Definitions (apidef): Impacts developers and schema-based tooling by signaling the deprecation of the old PRM location.
  • Gateway (gateway): While no runtime code is changed, its behavior regarding PRM fallback and independence from the main OAuth2 switch is now explicitly tested and guaranteed.

Configuration Migration Flow

This PR supports the transition from a single, top-level PRM block to a more flexible, per-security-scheme definition. During the migration, both can coexist, with the gateway prioritizing the new structure but falling back to the legacy one for safety.

graph TD
    subgraph "Old Structure"
        A["authentication"] -- contains --> B["protectedResourceMetadata"];
    end

    subgraph "Migrated Structure (Coexistence)"
        C["authentication"] -- contains --> D["protectedResourceMetadata (legacy, deprecated)"];
        C -- contains --> E["securitySchemes"];
        E --|scheme_name|--> F["OAuth2"];
        F -- contains --> G["protectedResourceMetadata (new)"];
    end

    style D fill:#f9f,stroke:#333,stroke-width:2px

Scope Discovery & Context Expansion

This PR is a companion to a migration feature in the tyk-analytics (Dashboard) repository. Its scope is strictly limited to the gateway's role in supporting this migration. The gateway does not perform the migration itself; rather, the Dashboard handles the non-destructive copy of the PRM configuration from the old location to the new one.

The key context is that the migration is non-destructive, meaning the original data is left in place for downgrade safety. This PR ensures the gateway handles this dual-state correctly by:

1. Prioritizing the new per-scheme PRM block if it exists.
2. Falling back to the legacy top-level block if the new one is absent.

The changes introduce no new runtime behavior and carry minimal risk, as they consist solely of documentation, schema updates, and tests that enforce existing functionality.

Powered by Visor from Probelabs

Last updated: 2026-06-08T10:52:45.219Z | Triggered by: pr_updated | Commit: f56cfb0

💡 TIP: You can chat with Visor using /visor ask <your question>

✅ Security Check Passed

No security issues found – changes LGTM.

✅ Performance Check Passed

No performance issues found – changes LGTM.

✅ Quality Check Passed

No quality issues found – changes LGTM.

Powered by Visor from Probelabs

Last updated: 2026-06-08T10:52:37.892Z | Triggered by: pr_updated | Commit: f56cfb0

💡 TIP: You can chat with Visor using /visor ask <your question>

🎯 Recommended Merge Targets

Based on JIRA ticket TT-17176: Protected Resource Metadata — auto-migration of existing customers

Fix Version: Tyk 5.14.0

⚠️ Warning: Expected release branches not found in repository

Required:

• master - No matching release branches found. Fix will be included in future releases.

📋 Workflow

1. Merge this PR to master first

🚨 Jira Linter Failed

Commit: f56cfb0
Failed at: 2026-06-08 10:51:42 UTC

The Jira linter failed to validate your PR. Please check the error details below:

failed to get Jira issue: failed to fetch Jira issue TT-17176: Issue does not exist or you do not have permission to see it.: request failed. Please analyze the request body for more details. Status code: 404

Next Steps

• Ensure your branch name contains a valid Jira ticket ID (e.g., ABC-123)
• Verify your PR title matches the branch's Jira ticket ID
• Check that the Jira ticket exists and is accessible

This comment will be automatically deleted once the linter passes.