Problem

When using ResourceTemplates with URI parameters that contain special characters (like forward slashes), there are two main UX issues:

1. Ugly encoded values in completion UI: Users see URL-encoded strings like kubernetes%2Fapps-use2-prd instead of readable names like kubernetes/apps-use2-prd
2. URI path conflicts: Even with proper encoding, URIs with special characters in template parameters can cause path resolution issues

Current Workaround

Currently, developers have to choose between:

• Using URL encoding (ugly UX, potential resolution issues)
• Using custom separators like -- (readable but non-standard naming)

Proposed Solution

1. Support Display Names vs Values in Completion

Allow completion functions to return objects with separate display and value properties:

complete: {
  authPath: async (_arg: string): Promise<Array<string | {display: string, value: string}>> => {
    return [
      { display: "kubernetes/apps-use2-prd", value: "kubernetes%2Fapps-use2-prd" },
      { display: "github-oidc", value: "github-oidc" }, // or just strings for simple cases
      "aws" // backward compatibility
    ];
  }
}

2. Automatic URI Encoding/Decoding

The SDK should automatically:

• URL-encode template parameters when constructing URIs
• URL-decode template parameters when passing to readCallback
• Handle this transparently so developers don't need to manage encoding

Use Case

We're building Vault auth method resources where paths like kubernetes/usw2-dev contain forward slashes that conflict with URI path structure. This pattern is common in many systems (file paths, namespace hierarchies, etc.).

Example

// What users see in completion
"kubernetes/apps-use2-prd"

// What gets encoded in URI  
"vault://auth/kubernetes%2Fapps-use2-prd"

// What readCallback receives (decoded)
variables.authPath === "kubernetes/apps-use2-prd"

This would provide a much better developer and end-user experience for ResourceTemplates with hierarchical or special-character naming schemes.