✨ Proposal: Standardize Efficient Object Graph Serialization

[scottslewis]

Describe the inspiration for your proposal

I've read through the spec, but am not a previous participant in the json or json schema spec creation process. I have participated, however, in open source spec creation and implementation.

It's becoming common now to use json+schema as the serialization format for client-server protocols. For example, the Model Context Protocol.

When serializing an object graph with references, the default serialization strategy for most existing libraries is to serialize multiple copies (by value) of any references.

For object graphs (e.g. trees), however, this results in multiple copies of the object being serialized to the stream...e.g.:

TreeNode has field 'parent' which is reference to TreeNode definition (recursive) and several other properties that are not references (e.g. type string).

A.parent is null

B.parent -> A
C.parent -> A
D.parent -> A
etc.

If B, C, and D are serialized to a stream, by default there will be multiple (3) copies of A on the stream. When there is only 1 needed for deserialization and validation.

Several libraries have a mechanism to deal with this...e.g. @JsonIdentityInfo for Jackson, Another is JavaScript Object Graph. I expect there are others and I'm just not aware of them.

These 'dynamic object identity' implementations mostly differ in the name and type of the dynamically added object identity. This variation makes it more difficult to support a multi-language protocol (like MCP).

Is there something in the existing schema spec currently or planned that would allow cross lib/cross language interoperability for serializing object graphs efficiently? If not, would a proposal be desired?

Describe the proposal

TBD

Describe alternatives you've considered

TBD

Additional context

TBD

[gregsdennis]

I think this is an interesting and useful idea, but it is somewhat outside the scope of JSON Schema, which is explicitly only evaluation (validation & annotation) of data.

I recommend creating a new specification for this.

---

JSON Schema does employ a reference mechanism that could be co-opted for this purpose, and we had started considering extracting that mechanism into its own spec, but that never gained traction.

In your example it would result in something like this:

A.parent is null

B.parent: {$ref: A}
C.parent: {$ref: A}
D.parent: {$ref: A}

However, in my experience, such bidirectional references wouldn't be encoded in a full serialization of the graph. I'd do a single 'parent -> child' in the serialization and then restore the back-reference upon deserialization.

[scottslewis]

Hi Greg. Thanks for the quick reply.

I think this is an interesting and useful idea, but it is somewhat outside the scope of JSON Schema, which is explicitly only evaluation (validation & annotation) of data.

I recommend creating a new specification for this.

I'm willing to do/participate in creating a new specification, but specification for what/to whom? (if it's out of scope for json schema?).

JSON Schema does employ a reference mechanism that could be co-opted for this purpose, and we had started considering extracting that mechanism into its own spec, but that never gained traction.

I will take a look at this referencing spec...obviously what I'm referring to is serialization (and stream identity) of object references of json schema-defined objects...that's why I thought it was relevant to the schema spec.

FWIW, I did spend some time looking for a json referencing specification that dealt with stream specific object identity (e.g. JSONRpc message rather than a full json document that contains all references to all objects). I did find an old draft but it apparently never got through the json process. LMK and I will re-find it as this was a couple of months ago.

In your example it would result in something like this:

A.parent is null

B.parent: {$ref: A} C.parent: {$ref: A} D.parent: {$ref: A}

I think the problem is, what is used to identify the A instance (i.e. the value of the ref in a given stream)? It has to identify the instance of possibly many As, not just the A type (as per schema). There may be no id/unique name property for the type of A, but there might be multiple/separate instances on sender (with distinct values of other properties) that should be turned (back) into a separate instance rather than a object reference.

As well, without JsonIdentiyInfo/jsog, there may be multiple copies of a given instance (serialized with multiple references to the same instance) that actually should be a single instance with multiple refs to it upon message de-serialization.

However, in my experience, such bidirectional references wouldn't be encoded in a full serialization of the graph.

I have tried multiple libraries (pydantic, Jackson, typescript library, etc) and they all encode multiple references to the same instance as a new copy....i.e. when it's a stream (message) rather than a full json document that contains all references.

[gregsdennis]

json schema-defined objects

I think this is the disconnect. JSON Schema doesn't define serialization or any relationship to the application objects that the JSON it's validating may represent. It sees JSON and validates (and annotates).

What you're looking for is an approach for serialization, which would be a step before JSON Schema enters the picture.

what is used to identify the A instance?

We use JSON Pointers. If you have an object graph, it's expected to have a root. Then the A is going to be defined somewhere in that graph, so you identify it by describing its location relative to that root with a pointer. Thus, the {$ref: A} will really be {$ref: <pointer to A>}.

when it's a stream (message) rather than a full json document that contains all references.

I don't follow this. Why would the JSON be different streaming than fully loaded? Whether it's being streamed or not seems orthogonal to references. Sure, you may not have received a reference target yet, but then you would just record that as a reference and resolve it after the stream finished. Otherwise, you'd have to require that any reference targets are included in the stream prior to any references to it. That would make recursive structures quite difficult, if not impossible.

[scottslewis]

json schema-defined objects

I think this is the disconnect. JSON Schema doesn't define serialization or any relationship to the application objects that the JSON it's validating may represent. It sees JSON and validates (and annotates).

I understand that, but json schema also defines types.

What you're looking for is an approach for serialization, which would be a step before JSON Schema enters the picture.

I agree. My original tack on standardization was to look at the json pointers.

I found this: https://json-schema.org/draft/2020-12/relative-json-pointer

which, unfortunately, has apparently been abandoned/not accepted/etc (I'm not familiar with json specification process either...perhaps you can refer me to people there) and seems to be dead.

The relative json pointer draft above is also way more than is needed to solve this particular problem (serialization/deserialization) however. IMHO this problem could be satisfied by standardizing a 'dynamic/stream id name and value type' without the relative json pointer spec support for full relative pointers in the stream. And...I don't know what happened with the relative json pointer spec originally and don't really want to get pulled into battle about that whole specification.

what is used to identify the A instance?

We use JSON Pointers. If you have an object graph, it's expected to have a root. Then the A is going to be defined somewhere in that graph, so you identify it by describing its location relative to that root with a pointer. Thus, the {$ref: A} will really be {$ref: <pointer to A>}.

Right. But in streams (as opposed to documents) it needs to be a relative pointer.

when it's a stream (message) rather than a full json document that contains all references.

I don't follow this. Why would the JSON be different streaming than fully loaded?

Because some/all instances (e.g. a tree or object graph) may have been created dynamically on the server.

Let's say a single 'e.g. top-level' instance of A is created and 200 children of A are created dynamically on a server...all pointing to the single instance of A (each with different values of other properties).

When each child is serialized to a stream in response to a message, without any further serialization/de-serialization hints (like JsonIdentityInfo or jsog) 200 copies of the A instance will be put on stream...because of the 200 references to the single A.

Please consider looking at the jsog repo docs.

Whether it's being streamed or not seems orthogonal to references.

Absolute references/pointer (whole json docs), stream (relative pointers) not.

Sure, you may not have received a reference target yet, but then you would just record that as a reference
and resolve it after the stream finished.

In this case the stream is a client -> request -> server response -> client protocol (json rpc). So 'resolving after the stream finished' can't mean sending a new message (new stream). Thus the need to support object graphs and relative pointers.

Otherwise, you'd have to require that any reference targets are included in the stream prior to any >references to it. That would make recursive structures quite difficult, if not impossible.

Yeah...there can be cycles of course with object graphs. Please take a look at the jsog docs....or JsonIdentityInfo as the both do the same thing.

I appreciate your point about json schema being about validation and not serialization, but I do think this (efficient serialization/deserialization of object graphs) is a issue that many library authors (dev users) have/are experiencing right now...and cross-lib and cross-language support becomes difficult without some sort of cross-impl agreement (maximally on relative pointer refs, minimally on dynamic id name/value type).,

So I guess I'm asking for your help in navigating the relevant spec process in json spec world. IMHO efficient object graph ser/deser sort of falls in between json pointers and json schema, as it involves both. That's why I'm asking here and not the json pointer specification (which seems far less active as well).

[gregsdennis]

Let's say a single 'e.g. top-level' instance of A is created and 200 children of A are created dynamically on a server...all pointing to the single instance of A (each with different values of other properties).

When each child is serialized to a stream in response to a message, without any further serialization/de-serialization hints (like JsonIdentityInfo or jsog) 200 copies of the A instance will be put on stream...because of the 200 references to the single A.

For this case, we use URIs. A URI identifies a resource that can be referenced later. For us, that resource needs to be a schema. For OpenAPI, that resource can be one of several kinds of objects (including schemas). In general, though, supposing you wanted to use $ref in plain JSON data, you can assign a URI to your JSON and then a $ref with that URI implies a reference to that JSON resource.

And just like schemas, JSON resources wouldn't need to be a full document or even at the root. You could define embedded resources if you wanted to. You'd likely need some mechanism for that, like how JSON Schema uses $id.

This is the problem that the reference spec I mentioned was supposed to solve.

I do think this (efficient serialization/deserialization of object graphs) is a issue that many library authors (dev users) have/are experiencing right now...and cross-lib and cross-language support becomes difficult without some sort of cross-impl agreement (maximally on relative pointer refs, minimally on dynamic id name/value type).,

I don't disagree, but JSON Schema isn't the spec to solve that particular problem. There needs to be another spec.

[scottslewis]

> For this case, we use URIs. A URI identifies a resource that can be referenced later.

I don't think URIs are what's needed. Object graphs aren't intended to be durable/long lasting or public. URIs/file systems are typically both. Also, URIs are just unique identifiers. What if the object A has 5 other (e.g. string) properties that should be serialized and de-serialized along with the name

And just like schemas, JSON resources wouldn't need to be a full document or even at the root.

But schemas define the types, not the instances.

This is the problem that the reference spec I mentioned was supposed to solve.

Which reference spec was that?

> > I don't disagree, but JSON Schema isn't the spec to solve that particular problem. There needs to be another spec.

Another spec submitted to which organization/group? json IETF? json schema? (apparently you don't object graphs are in scope), someone else?

The reason I ask is that I don't want to create my own standards org to be able to submit a request for a dynamic (ser/deser) id property name and value type :)...e.g. here's my/jsog spec draft for json generator and parser implementers:

optional object identity

property name: "@id"
property type: string

This is much simpler than the relative pointer spec...even though I think that spec would do what's needed here it does far more than is needed.

[gregsdennis]

Which reference spec was that?

https://github.com/json-schema-org/referencing

schemas define the types

This was my point from before. JSON Schema isn't designed for type definition. People tend to use it that way, but... https://modern-json-schema.com/json-schema-is-a-constraint-system.

Can you use JSON Schema to define types? Yes, to an extent, but there are concepts in types (like inheritance) that just can't be expressed with schemas (at least not that we've yet devised), and there are concepts in schemas that are fundamentally incompatible with types.

Schemas don't define types; they describe a JSON values. It's pedantic, but a distinction.

[scottslewis]

> > > schemas define the types > > This was my point from before. JSON Schema isn't designed for type definition. People tend to use it that way, but... https://modern-json-schema.com/json-schema-is-a-constraint-system. > > Can you use JSON Schema to define types? Yes, to an extent, but there are concepts in types (like inheritance) that just can't be expressed with schemas (at least not that we've yet devised), and there are concepts in schemas that are fundamentally incompatible with types.

Just for the record...this isn't inheritance I'm trying to express. Rather it's just a single/special-but-important case of json relative pointers. FWIW, I agree that some OO concepts are not well-expressed by schemas.

Schemas don't define types; they describe a JSON values. It's pedantic, but a distinction.

With due respect...yes, it's pedantic.

The fact is, nearly every protocol I've seen (including MCP) that's based upon json as the serialization format uses the json schema to do two things:

1. specify the protocol

2. Use the schema to provide types for implementation and serialization/deserialization via pydantic (or Jackson, or whatever).

Feel free to convince the MCP folks (or the other protocols that are based upon json rpc) that they need to stop using schemas to define types of objects to be serialized and de-serialized to/from the wire.

I'm not arguing that this is somehow correct, but it is the way people are doing things. And so I would like to make it possible (and as efficient as possible) to not have to redo all implementations.

So back to my other question: If not json schema and org for specifying something like this, then what?

Thanks and inadvance.

[gregsdennis]

Yes. I'm still of the firm opinion that the JSON Schema specification is not the right place to define serialization methods. That needs its own specification, but I'm sure you could use JSON Schema to help provide whatever approach that specification defines.

I see it much like OpenAPI. It defines a document format that describes APIs. It uses JSON Schema to do that. But it's not JSON Schema's place to define APIs, so they created their own spec.

Another example is form generation. JSON Schema is often used for this, but it's not in scope for the spec. I think this is a great opportunity for an extension spec.

[scottslewis]

Yes. I'm still of the firm opinion that the JSON Schema specification is not the right place to define serialization methods. That needs its own specification, but I'm sure you could use JSON Schema to help provide whatever approach that specification defines.

I see it much like OpenAPI. It defines a document format that describes APIs. It uses JSON Schema to do that. But it's not JSON Schema's place to define APIs, so they created their own spec.

Another example is form generation. JSON Schema is often used for this, but it's not in scope for the > spec. I think this is a great opportunity for an extension spec.

By 'extension spec' do you mean a json schema extension spec? Or some other existing org/spec extension?

Actually, one could consider jsog very close to a specification (as well as implementations) right now, as the impls do work across languages and serialization libraries...by defining the synthetic '@id' property with value type string (unique for the relevant schema-defined types).

So...any suggestions (organizations and/or names) of who to submit this extension specification to? i.e. to get to lang and library interoperability wrt object graph ser/deser? (my actual goal here...not particularly to produce or a specification).

Thanks.

[jdesrosiers]

First, here's background and information that I hope you will find helpful. Then, I'll share my thoughts and opinions.

If not json schema and org for specifying something like this, then what?

Unfortunately, there's no satisfying answer to this question. The JSON media type is considered "done". There's no one working on it and it's never going to change. I'm sure that's not surprising, but what people do find surprising is there isn't a group somewhere collaborating on writing and promoting specifications related to JSON. Things like JSON Schema, JSON Pointer, JSON Path, and dozens of other specification in the JSON ecosystem are generally unrelated and worked on by different people who often aren't aware of what others are doing. So, you can go around to the different standards organizations (IETF, W3C, Ecma, etc) and see if anyone is interested in picking up your idea, but as far as I know, no one has an active working group working specifically on JSON-related technologies that you should be going to first.

I found this: https://json-schema.org/draft/2020-12/relative-json-pointer

which, unfortunately, has apparently been abandoned/not accepted/etc (I'm not familiar with json specification process either...perhaps you can refer me to people there) and seems to be dead.

Relative JSON Pointer came from us. So, we've had a bit of a weird relationship with IETF. We use their tool chain for building our specs, but we aren't actually associated with IETF in any way. So, things say "draft" and "expires" in our documents, but we don't treat them as drafts or consider them to ever expire. We consider it done and usable. It's not abandoned. It was originally created as part of a JSON Hyper-Schema feature that's since been abandoned, so we don't really use it for anything. I don't think we know about anyone using it either. If we find it people are actually using it, we might try to get it adopted by IETF, but until then, it's done.

---

I think this is an interesting topic. It could have some relation to JSON Schema, but we'd have to change some of how JSON Schema defines references and it might be a little different than what you have in mind.

I've always wanted us to define a JSON Reference (JRef) media type. Then instead of JSON Schema defining "$ref", we would just write our schemas using JRef (which defines "$ref") instead of plain JSON. JRef could be used for serializing/deserializing arbitrary JSON documents with cycles as well. All the specs that use "$ref" could use JRef instead of defining their own way of doing "$ref". Given that vision, I can see this issue being in scope for JSON Schema. But, what actually happened was that instead of being a generic media type that can be used by everyone, we all defined our own different versions of "$ref". I don't see that changing. Maybe it's worth building that spec in hopes that it gets adopted in the future, but I don't know if that's realistic. I don't think it's realistic even here at JSON Schema.

Other than that, I don't see a connection to JSON Schema.

Regarding streaming, I don't think streaming and referencing mix well. The point of streaming is that you don't have to hold a bunch of data in memory. But, any part that could be referenced would need to be held in memory in case they get referenced. Sometimes that's literally the whole document completely negating the point of processing the JSON as stream in the first place. I think when you choose streaming, you're accepting the trade off that you might be sending extra data sometimes for the benefit of not having to hold that data in memory.

But, I'm not sure you're actually talking about processing JSON as a stream. You say,

FWIW, I did spend some time looking for a json referencing specification that dealt with stream specific object identity (e.g. JSONRpc message rather than a full json document that contains all references to all objects).

A JSONRpc message is a JSON document. You're receiving a stream of JSON documents, not processing the JSON as a stream, right? Is the hangup that these messages don't have identifiers? That shouldn't make any difference. Local references should be enough.

{
  "jsonrpc": "2.0",
  "method": "foo",
  "params": {
    "people": {
      "Jim": {
        "spouse": { "$ref": "#/params/people/Mary" }
      },
      "Mary": {
        "spouse": { "$ref": "#/params/people/Jim" }
      },
      "Tom": {
        "mother": { "$ref": "#/params/people/Jim" },
        "father": { "$ref": "#/params/people/Mary" }
      }
    }
  }
}

Let me know if I'm missing the point, but at this point, I don't see the need for Relative JSON Pointer.

I don't think URIs are what's needed.

Hopefully, whatever comes out of this is useful in a lot of different contexts. Using URIs may not be necessary in the contexts you're thinking of, but there are other context where it is useful. So, I think using URIs doesn't hurt in cases where it's not necessary, but makes more things possible. Check out this demo of an API that allows you to click through the graph of data represented with the JRef media type I described earlier. It's solving the same kind of problem, but in a context where a URI is necessary.

[scottslewis]

First, here's background and information that I hope you will find helpful. Then, I'll share my thoughts and opinions.

Yes I found it helpful, thanks very much.

If not json schema and org for specifying something like this, then what?

Unfortunately, there's no satisfying answer to this question.

That's a pity. Right or wrong, my observation is that Json and Json schema are now being heavily used to specify and implement new protocols (e.g. MCP). I'm not sure that would be my own choice, but it is happening.

Like I've said above...all I'm looking for is interoperability at the wire protocol level between clients/servers/langs/libraries. MCP for example, is just beginning to do schema conformance testing...i.e. python clients/rust servers, typescript clients/java servers.

Trying to introduce things like support for efficient object graph serialization is going to be extremely difficult if there's no consistent approach that the sdks implementers can agree on (e.g. jsog).

Relative JSON Pointer came from us. So, we've had a bit of a weird relationship with IETF. We use their tool chain for building our specs, but we aren't actually associated with IETF in any way. So, things say "draft" and "expires" in our documents, but we don't treat them as drafts or consider them to ever expire. We consider it done and usable. It's not abandoned. It was originally created as part of a JSON Hyper-Schema feature that's since been abandoned, so we don't really use it for anything. I don't think we know about anyone using it either. If we find it people are actually using it, we might try to get it adopted by IETF, but until then, it's done.

Perhaps just simplification of the json relative pointer spec? Or perhaps parts could be introduced incrementally?

My belief/expectation would be if all it allowed was the equivalent of jsog (dealt with this efficiency problem) it would be immediately adopted at a very large scale just for the efficiency gains/bandwidth reduction for certain use cases.

I think this is an interesting topic. It could have some relation to JSON Schema, but we'd have to change some of how JSON Schema defines references and it might be a little different than what you have in mind.

I've always wanted us to define a JSON Reference (JRef) media type. Then instead of JSON Schema defining "$ref", we would just write our schemas using JRef (which defines "$ref") instead of plain JSON. JRef could be used for serializing/deserializing arbitrary JSON documents with cycles as well. All the specs that use "$ref" could use JRef instead of defining their own way of doing "$ref". Given that vision, I can see this issue being in scope for JSON Schema. But, what actually happened was that instead of being a generic media type that can be used by everyone, we all defined our own different versions of "$ref". I don't see that changing. Maybe it's worth building that spec in hopes that it gets adopted in the future, but I don't know if that's realistic. I don't think it's realistic even here at JSON Schema.

Seems like JRef approach would be great.

Other than that, I don't see a connection to JSON Schema.

Regarding streaming, I don't think streaming and referencing mix well. The point of streaming is that you don't have to hold a bunch of data in memory. But, any part that could be referenced would need to be held in memory in case they get referenced. Sometimes that's literally the whole document completely negating the point of processing the JSON as stream in the first place. I think when you choose streaming, you're accepting the trade off that you might be sending extra data sometimes for the benefit of not having to hold that data in memory.

I think I've been using 'streaming' when what I really mean is messaging. MCP...and most of the JsonRPC 2 protocols I've seen, uses request -> response messages to defining the protocol. LMK if you want pointers to their schema or docs. There are types of requests, and types of responses (e.g. listtoolsrequest, listtoolsresult, listpromptrequest, etc. Where the json schema-defined types come in is as the payload for these messages. The payload of the listtoolsresult, for example is a array of schema defined Tool objects. Sorry...I meant message payload rather than stream.

And the payload for every message may very well have refs to other instances of other types...e.g. Tools might point to other ToolGroups. That's where the object graph comes in...as each message has to include a copy (by default) of every object reference. For example, if 5 Tools point/refer to the same ToolGroup, the json serialization (by default in all impls) will put 5 copies of the same ToolGroup in the listtoolsresult payload. 5 copies is way more than needed...enter jsog/JsonIdentityInfo or relative pointers...where a single/1st ToolGroup copy serialized in payload can then be referred to by all other Tools.

Although it can obviously be made to work, creating multiple request/result messages (e.g. listgroups + listtools + client side resolving of ids to a local copy of the object graph) works but at a the cost of another round trip between client/server. Sometimes that makes sense, but sometimes it doesn't. Sometimes it's already been specified and can't change without breaking all clients and servers.

Again thanks to both for jumping in. That's appreciated.