Metadata/headers for RPC messages

[Anuraag Agrawal]

Hello,

I am looking at propagation of context across RPC messages mostly in the context of MCP and tracing. This is a more generic issue of attaching metadata to messages semantically similar to HTTP headers. Is there any movement in adding these natively to JSON-RPC itself? Currently, such metadata needs to be defined in downstream protocols themselves, and I have found three different ways and there could be more.

MCP: _meta field within params - https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2024-11-05/schema.ts

SourceGraph: meta field at top level - https://github.com/sourcegraph/jsonrpc2/blob/master/request.go#L24

VSCode: top level fields - https://github.com/microsoft/vs-streamjsonrpc/blob/main/docfx/docs/tracecontext.md#text-encoding

It seems like there is a strong need for generic per-message metadata that is not the actual RPC payload and if this was standardized, implementations could be simpler and more interoperable, especially for cases like tracing which rely on all nodes to be propagating in the same way. Is something like that possible? Personally I would recommend the SourceGraph schema of a top level meta field so it has some structure while still being clearly decoupled from params (the decoupling is to distinguish RPC method payload vs generic metadata).

One other thing to keep in mind is the notion of leaving it to the transport layer to carry metadata - this can't be per-message though if the transport is not, i.e. MCP uses a SSE stream to send many independent messages in a single HTTP request. HTTP headers cannot be used for per-message metadata. And some transports like Kafka may have no structure at all.

Thanks,

[Anuraag Agrawal]

Sorry for the double-email, I had forgotten to link to the previous work I had found on the email list related to the topic. There are at least a couple of threads that are several years old

https://groups.google.com/g/json-rpc/c/l7m5SIvwnFs/m/bHNGlIQ3BAAJ

https://groups.google.com/g/json-rpc/c/YDLSE668ZZ8/m/3W4xDjcUAAAJ

From my reading, there was never any strong opposition to the idea but just didn't actual move on to any spec change. But maybe with examples of usage in the wild now, there could be more momentum in making a change.

Thanks,

[Jonathan Hefner]

I agree it would be helpful to define an official top-level `meta` property.  I think it would be good to define it not just for request objects, but for response objects as well.  Here are a few uses cases for a response `meta` property:

• Including performance metrics.  For example, number of database queries executed to compute the response, or amount of memory allocated.
• Roundtripping framework-level data between calls.  For example, a framework client could set `request.meta.foo` before sending a request, and the framework server could copy that value to `response.meta.foo` before sending the response.
• Reporting side effects.  For example, if the server can enter a different mode as the side effect of a request, then the server's mode could be reported with `response.meta.mode`.

[Matt (MPCM)]

Hi all, looks like there is going to be a bunch of inbound MCP-related discussion based on the links I've seen posted elsewhere also. :)

I think the concept is worth discussing in general, and I see value in the concept of such meta data... but not really the "strong need for generic per-message metadata" in the spec itself. 

The way this should work is to just include the new field in your objects, and write a separate extension spec that details the use of the field, its shape and data, and suggestions around using/processing it, and start the process that way to build consensus. Especially once the 'JSON has too much wire bloat crowd' re-arrives in a few weeks time.

Existing client/server implementations should ignore (broadly speaking) additional fields anyway if they are playing nice. The question then really becomes more about the meta data (in or out), should it be part of an enveloped in json-rpc objects, especially if the api is reading/adding this data, or if this is more like proxy layer headers of some kind, essentially routing or routing perf data. From what I have read so far, it seems like the answer is going to be both or either for a while as MCP finds it's footing.

So..., happy to see the discussions around the topic. Very much like trace data, flame graph data, tokens consumed, dollars spent, etc. I don't think it needs to worry about becoming 'part' of the json-rpc spec as such, so much dust has to settle still. But while you are settling it, this is exactly what an extension spec should be working through without the goal of being in the base spec IMO.

( To address other topics I got linked into elsewhere that will end up pointing back here, this isn't an thing I see causing a 2.1 specification jump. But I also see json-rpc as largely settled.... conceptually anyway, and fwiw.)

I'll read through the links you posted a bit more. I do feel you are right ... it only works in http headers for single payloads. If you have multiple payloads, you need to have multiple structured headers, and everything starts to feel ugly, and like you dont have cohesion of concept. Especially if you are encrypting/signing payloads in addition to transports.... "what a time to be alive". :)

[Anuraag Agrawal]

Hi Matt,

Thanks for the insight. I think extension specs is basically maintaining the status quo, with the three examples I linked effectively being extension specs. Naturally it's up to spec maintainers to decide what's in scope for JSON-RPC and if a bag for metadata isn't, then downstream specs will define it as they currently do. A few points that might add some clarity

- I mentioned MCP mostly as the lead-in to the discussion and since it's useful to have examples in mind when designing, but I think it's also good not to look too far into it. How a meta field is used will always be up to the users, but having a blessed field that is a bag of metadata in JSON-RPC could be useful without overspecification to provide a base for the downstream protocols as well as potential interoperability. Without any definition or required fields within it, I don't think it would contribute to wire bloat.

- I think the idea for the field is closer to your suggestion of proxy layer headers type of thing, while downstream protocols may have more creative usage as well. Notably, if using tracing as an example, having a well-defined bag for this metadata could allow a JSON-RPC gateway server to participate in a trace regardless of the use case, just like HTTP gateways can. Without, a gateway server would need to be configured to the field it needs to inspect for trace IDs which is also doable but not automatic.

- HTTP is the most commonly used envelope protocol and I think we clearly see very common patterns in terms of using HTTP headers separately from payloads, and as mentioned above enables usages such as generic gateways. If JSON-RPC doesn't have a similar mechanism, it feels like a feature gap between the two, with transferring existing HTTP patterns becoming more challenging.

As mentioned, none of these are blockers - JSON objects are open and can have any fields added to them, even the top-level ones. But standardizing a mechanism for this sort of metadata could enable more useful JSON-RPC tooling - on the flip side, if not standardizing, there will be divergence as we already see and instead of JSON-RPC tooling, it'll be MCP tooling, Sourcegraph tooling, etc. This is reasonable too if it's out of scope for JSON-RPC itself, but hopefully that can be some more context on deciding if it is or not.

Thanks,

--
You received this message because you are subscribed to a topic in the Google Groups "JSON-RPC" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/json-rpc/pFFuI0JN8Cs/unsubscribe.
To unsubscribe from this group and all its topics, send an email to json-rpc+u...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/json-rpc/fab69105-bac3-46bb-907c-c2fe8919b30en%40googlegroups.com.