[whatwg/url] URL.toJSON() returns a string, not an object — misleading name, consider toJSONObject (Issue #888)

AndrewEQ created an issue (whatwg/url#888)

### What is the issue with the URL Standard?

## Summary
Currently, `URL.prototype.toJSON()` returns the same string as `href`. While this works correctly with `JSON.stringify()`, the method name `toJSON()` is potentially misleading. Many developers reasonably expect `toJSON()` to return a **JSON object**, not just a string.

Historically, `Date.prototype.toJSON()` was the first built-in to define `toJSON()`, returning a string (ISO 8601 format). `URL.toJSON()` follows the same pattern. This pattern continues with newer built-ins like `Temporal.PlainDate`, which also implements `toJSON()` returning a string rather than a structured object. This historical and ongoing pattern can lead to confusion when developers expect structured JSON output.

## Problem
- `toJSON()` duplicates `toString()`/`href` behavior.  
- The naming implies “return a JSON object,” but it returns a string suitable for `JSON.stringify()`.  
- Developers may reasonably expect `toJSON()` to return a structured object, especially when the name suggests JSON output.

## Proposal / Discussion Points
1. **Clarify intent in the spec:** Explicitly note that `toJSON()` is a *serialization hook for `JSON.stringify()`*, not a producer of structured JSON objects.  
2. **Introduce a structured JSON method (optional/future):**  
   - Proposed names: `toJSONObject` or `toJSONObj`  
   - Returns a proper JSON object representation of the URL, leaving `toJSON()` for legacy/compatibility.  
   - Example:
     ```js
     const u = new URL("https://example.com");
     u.toJSON();      // "https://example.com/"
     u.toJSONObject(); // { href: "https://example.com/", origin: "https://example.com", protocol: "https:" }
     ```
     > Note: The structured object could also include additional URL attributes such as `host`, `port`, `username`, `password`, `pathname`, `search`, `hash`, etc., depending on final design.
3. **Consider consistent implementation across similar objects:**  
   If a structured `toJSONObject` (or `toJSONObj`) method is accepted for `URL`, it could also be applied to other built-in objects that currently implement `toJSON()` as a string (e.g., `Date`, `Temporal.PlainDate`). This would provide a consistent and predictable API for developers wanting structured JSON output from built-ins.

## References
- [WHATWG URL Standard – URL.prototype.toJSON](https://url.spec.whatwg.org/#dom-url-tojson)  
- [ECMA-262 §21.4.4.45 Date.prototype.toJSON](https://tc39.es/ecma262/#sec-date.prototype.tojson)
- [MDN – Temporal.PlainDate.prototype.toJSON](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate/toJSON)

-- 
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/url/issues/888
You are receiving this because you are subscribed to this thread.

Message ID: <whatwg/url/issues/888@github.com>