How can an existing client extract the value property? It doesn't know about the value property.

I think to be backwards compatible, new servers need to return string if the client is not on the new version of the spec.

We cannot reasonably expect all clients to update before servers start rolling this out. I think the migration path should be that SDKs automatically extract the value and return that instead when talking to old clients.

and we'd need version bump

Commenting from the Go SDK side: I agree this is not an "additive, optional enrichment" as we're replacing a string in the schema with a union type. Go doesn't have union types, so this essentially means we need to replace string with a struct, which is a backwards incompatible SDK API change.

We would likely need to follow a similar path as we did with adding tools to sampling:

1. create a new variant of CompleteResult that has the changes applied,
2. add additional method for calling completion API on the client side that would use the new result type as a return type (e.g. CompleteWithMetadata in addition to existing Complete),
3. modify the existing Complete to strip the additional metadata if CompletionValues were returned from the server,
4. add additional handler type for completions on the server side (e.g. CompletionWithMetadataHandler in addition to existing CompletionHandler) that would use the new result type,
5. use the new handler for completion requests if provided and the most recent spec version was negotiated with the client, otherwise use the old handler.

Hope this helps!

I'm confused. I don't use completions much, so apologies if I'm missing something, but Isn't the idea of completions that the user types things and it shows a list of options prefixed by what you type? If the value is an ID (e.g. 1234) but the title is a user-readable string (e.g. Python), I assume the user is typing Pyt... not 123..., so the partial completion is the title, not the value? What value do you send if the user has typed Pyt...?

I think this is a real challenge, given the completion not search, it is meant to be the value, I think @evalstate is spiritually correct and the title would show to ensure the user is getting the expected completion result, but they'd have to type the actual value.

Places GitHub might use this:

• pull request number show titles
• commit sha show commit title
• issue number show title
• project ID show title

But you complete the value, the server gets the partial value to be completed and returns new completions as you type more chars, if you allow for typing the title it would mean:

• you'd have to rely on an initial completion request from blank string definitely returning results
• the client/user having to find the full value in the potentially partial initial completion result.

So yeah, I think this wording is correct as is.

In the motivation and context section it says:

With this setup, the user would naturally type the title rather than the ID and the server could filter based on the title (or any other field) instead of just the ID.

This seems to contradict what is being proposed?

or is the idea that the server will filter on both and return the union? So I can type either 12 or Py to get Python?