Opt-in Mechanism for Structured Clone Serialization and JSON Fallback Considerations

[justinlulejian]

Summary

This proposal suggests a standard mechanism for browsers to enable Structured Clone serialization for extension messaging (e.g., runtime.sendMessage, Port.postMessage, etc.) if they do not support it already. We are seeking feedback on which approach (or another) better serves the ecosystem.

Problem

Structured cloning offers significant advantages over JSON serialization (supporting more types like Map, Set, ArrayBuffer, and circular references), but it is not a drop-in replacement. It introduces potential breaking changes, such as stricter data handling (like failing on objects with keys that are functions, and etc.) where JSON might have silently ignored them, and behavioral differences (such as toJSON() methods on classes where structured cloning ignores them). Due to these potential breaking changes, a developer-controlled opt-in mechanism seems necessary to minimize disruption from adoption.

Proposal: Manifest Key

Chromium’s preference is to add a new manifest key that sets the default serialization behavior for the entire extension.

Manifest Example:

{  
  "name": "My Extension",  
  "version": "1.0",  
  "manifest_version": 3,  
  "message_serialization": "structured_cloning"  
}  

When this key is set to "structured_cloning", the browser will use the structured clone algorithm ("json" for JSON.stringify) for all message passing APIs within the extension context. If omitted the browser defaults to its current implementation (for Chromium that’s JSON.stringify) to preserve compatibility.

Advantages

• Wholesale Adoption: Simplifies global migration by eliminating the need to add a new "options" argument to every individual messaging call site.
• Simpler removal: In the future, if all browsers defaulted to structured cloning, removing a single manifest key (or ignoring it) is much simpler than requiring developers to change individual messaging callsites.

Disadvantages

• Library Compatibility: Third-party libraries that use extension messaging in the extension will also be forced to use structured cloning. If a library relies on specific JSON behavior (toJSON(), etc.), it may break without updates. This means extensions that rely on these libraries need to use whichever format the libraries do (they cannot update if they rely on a library that needs JSON serialization).

Other options:

Runtime Indication (Per-call Opt-in)

Alternatively, the serialization format could be specified at the individual call site via the existing options/info objects. For example, let’s look at the runtime API:

runtime.sendMessage
The options parameter would accept a serialization property.

chrome.runtime.sendMessage(  
  extensionId,  
  message,  
  { serialization: 'structured_clone' }  
);  

runtime.connect
The connectInfo parameter would accept a serialization property, determining the format for that specific port's lifetime.

const port = chrome.runtime.connect(extensionId, {  
  name: 'my-port',  
  serialization: 'structured_clone' 
});  
port.postMessage(new Map()); // Uses structured clone  

Advantages

• Granular Control: Developers can adopt structured cloning for specific features or messages and migrate libraries as they are able.

Disadvantages

• Verbosity: Requires developers to explicitly opt-in at every call site, increasing boilerplate and developer operational load.
• Standardization: If the WECG’s goal is for extension messaging to ultimately exclusively use structured cloning for serialization, then this could encourage a divided situation where developers use both serialization methods indefinitely.

JSON Fallback

Given that the above choices are binary, there perhaps can be a middle-ground where we don't need the opt-in and structured cloning can be enabled with backwards compatibility built-in? We could enable structured and use it in most cases, but could fallback to JSON in some edge cases? One example of where we might want to fall back to JSON serialization is classes with toJSON() methods:

class User {  
  constructor(name, password) {  
    this.name = name;  
    this.password = password;  
  }

  // Hide password when converting to JSON  
  toJSON() {  
    return { name: this.name };  
  }  
}

const user = new User("Alice", "secret123");

console.log(JSON.stringify(user));   
// Output: {"name":"Alice"}  <-- Password hidden

const clone = structuredClone(user);  
console.log(clone);   
// Output: { name: "Alice", password: "secret123" } <-- Password unintentionally exposed  

Advantages

• Ease: Developers can gain the benefits of structured clone serialization without having to take explicit action.

Disadvantages

• Maintenance Scalability: A fallback creates a complex, hybrid serialization logic. As the platform evolves, maintaining a growing list of exceptions for specific edge cases (like toJSON) may become technical-debt-heavy and difficult to support reliably across all browser engines.
• Inconsistent between browsers: Browsers would (continue to) behave differently when serializing messages, unless other browsers added support for a JSON fallback (which is then a behavior change for them).
• Hard to sunset: There is no clear migration path to remove support for JSON serialization in this case.

[tophf]

It introduces potential breaking changes, such as stricter data handling (like failing on objects with keys that are functions, and etc.) where JSON might have silently ignored them, and behavioral differences (such as toJSON() methods on classes where structured cloning ignores them).

The first issue is a huge problem in the Web platform's structured cloning as it essentially requires making a totally redundant deep copy of objects when using certain frameworks before sending, thus severely undermining the benefits of structured cloning (Vue framework as well as others use Proxy on observable objects which isn't sendable). It's just outrageous and AFAIK nothing's being done. In an ideal world the extensions people should fix it for extensions, then hopefully it gets adopted by the Web, just like they did adopt our background pages as service workers.

For example, provide a config (API or option) that enables sending just the Proxy's target object, the unserializable values omitted or replaced with a preset value, the unsupported keys (functions) are skipped or replaced with a preset value.

Proposal: Manifest Key

It's harder to test the differences in behavior as we would have to reload the extension, which closes all its tabs/windows/frames and invalidates the state in the content scripts unless the extension implements a sophisticated workaround.

Runtime Indication (Per-call Opt-in)

I like the idea (we use the options parameter to set frameId anyway), but I don't like the verbosity, so what about json: true assuming false is the default? If you say it's not self-evident, that's what documentation is for and it's a required reading anyway in order to understand the implications.

this could encourage a divided situation where developers use both serialization methods indefinitely.
no clear migration path to remove support for JSON serialization in this case

This is perfectly fine given the huge inherent problems with the structured clone algo mentioned above. It's quite possible that no one will want to solve them during our lifetime, so having both methods is a good practical solution.

It would make sense for chrome.runtime.setMessageSerialization() in addition to per-call opt-in to reduce the verbosity. It could be synchronous so it would work just for the current execution context and we wouldn't have to introduce yet another point of raciness due to the need to await for this API. Alternatively it can be a setter like chrome.runtime.messageAsJson = true which would clearly signal that's synchronous although not that it's just per context.

P.S. There's of course the workaround of explicitly using JSON.stringify() when sending and JSON.parse() when receiving, but that doesn't look like a platform'y solution at all (on top of nuking the nested complex types not compatible with JSON but sendable via structured cloning), it doesn't indicate a clear purpose so to anyone not familiar with the problems of the structure clone algo it would look like a novice mistake caused by not knowing the API is capable of sending objects.

[justinlulejian]

For example, provide a config (API or option) that enables sending just the Proxy's target object, the unserializable values omitted or replaced with a preset value, the unsupported keys (functions) are skipped or replaced with a preset value.

IIUC this sounds similar to the JSON fallback option, but with more granular controls on what to do in the cases that structured clone can't handle -- does that sound right? If not could you provide an example of how a developer would call this (generally, not just for Proxy objects)?

so what about json: true assuming false is the default?

Does this mean all messaging calls would assume structured clone serialization with the per-call opt-in solution? If so, this existing extensions could break if they don't expect the serialization though?

It's harder to test the differences in behavior as we would have to reload the extension, which closes all its tabs/windows/frames and invalidates the state...

Thank you for bringing this up, it is a significant consideration.

It would make sense for chrome.runtime.setMessageSerialization() in addition to per-call opt-in to reduce the verbosity... Alternatively it can be a setter like chrome.runtime.messageAsJson = true...

I enjoy the granularity vs boilerplate trade-off of this approach. I'm also thinking an extension-level browser.extension.setMessageSerialization() could also be helpful for simpler extensions that can decide wholesale (but, for Chromium at least, this would need to be an async call).

browser.runtime.messageSerialization = 'structured_clone'; seems like it could work instead too, but if we had a browser.extension version then I'd lean towards the method call so the API documents what is sync and async.

This is perfectly fine given the huge inherent problems with the structured clone algo mentioned above... having both methods is a good practical solution.

Regarding the issues with Proxies, toJSON(), etc.: I think Chrome is amenable to keeping JSON support so developers can continue to handle situations like this (and possibly others that could come up in the future), but I'm curious if other browsers are supportive of that since AFAIK that would be a change for them.

So, just in summary for other readers, here's the option proposed (@tophf let me know if I've gotten any details wrong):

Runtime Configuration (Context-Level Default + Per-Call Override)

This approach combines the granularity of per-call options with the convenience of a context/extension-level default.

1. Set a default for the context (or extension) (reduces verbosity):

// At the top of background.js or a content script
// Sets the default serialization for all subsequent calls in this context
browser.runtime.setMessageSerialization('structured_clone');

// Synchronous and every future message created will use this format in any extension context.
await browser.extension.setMessageSerialization('structured_clone');

2. Override per-call (handles edge cases & libraries):

// Uses the `setMessageSerialization()` call value, or context default if not called.
chrome.runtime.sendMessage(extensionId, complexMapObject);

// Explicitly opts out (e.g., Vue+Proxy object, toJSON())
chrome.runtime.sendMessage(extensionId, proxyObject, { serialization: 'json' });

Advantages

• granularity+convenience: Could mitigate the verbosity issue of the per-call opt-in, while also mitigating the rigidity issue of the manifest key.

Disadvantages

• Implementation complexity: Naturally, due to the flexibility of this option, I presume this would have the most implementation complexity (I can speak for Chrome that this is the case).
• API Surface: Increases the API surface slightly by adding both a property/setter and an options parameter.

[tophf]

more granular controls on what to do in the cases that structured clone can't handle [...] how a developer would call this [...]?

Probably extension.setMessageSerialization({type: 'structured', useToJSON: true, useProxyTarget: true}).

Does this mean all messaging calls would assume structured clone serialization with the per-call opt-in solution?

No, I'll pretend my example assumed the developer switched the default mode :-)

implementation complexity

FWIW browsers can start with the simpler implementation in manifest.json and look at the dev community feedback. BUT you'll need to expose the capability somehow so extensions that target multiple versions of the browser can massage the messages depending on the feature being active e.g. expose a constant or an object in browser.runtime which is available in all contexts where messaging is exposed, including the isolated worlds of content scripts and userscripts with enabled messaging.

[Rob--W]

Summary of support statuses:

• Firefox currently supports structured cloning only. Willing to consider JSON serialization support if there is significant demand for it.
• Safari supports JSON serialization only. Supportive of adopting structured cloning, but without specific commitment to scheduling the implementation.
• Chrome currently supports JSON serialization with the desire to support structured cloning.

In today's meeting, the preference across browsers is to start with a manifest key to enable extensions to explicitly express the preferred behavior.