req icon indicating copy to clipboard operation
req copied to clipboard

`json`: Support optional use of `:json` in OTP 27+

Open zachallaun opened this issue 7 months ago • 4 comments

With the release of :json in OTP 27, I think it's worth discussing how Req might support its (optional) use. I don't feel strongly that Req should support it (more on that below), but I figured a discussion would be worth having that could at least be pointed to in the future when the topic comes up!

Some points for context:

  • As of v0.5.2, Jason is one of Req's three required dependencies, alongside Finch and MIME. (Other de/encoding deps, such as NimbleCSV, brotli, et al. are optional.)
  • Req uses the following from Jason, not all of which have a direct correspondence in :json:
    • Jason.encode_to_iodata!/1 (opts not supported) - corresponds to :json.encode/1 (returns iodata and raises on error)
    • Jason.encode!/1 (opts not supported) - equivalent to value |> :json.encode() |> IO.iodata_to_binary()
    • Jason.decode/2 (opts supported with :decode_json) - no direct correspondence, :json.decode/3 raises on error and does not support high-level opts like keys: :atoms, but requires that the same effect be implemented using callbacks
  • One potentially critical component missing from :json is the protocol support that Jason provides for struct encoding. Whereas Jason will error when attempting to encode a struct that doesn't implement Jason.Encoder, :json will happily encode to {"__struct__": "Elixir.MyStruct", ...}.

Given that :json is not a drop-in replacement for Jason, I see a few ways forward:

  1. Do nothing and wait. There's an issue in the Jason repo (michalmuskala/jason#185) suggesting that the current plan is to propose an Elixir standard library wrapper around :json. We could wait for that and continue to depend on Jason. (It's possible that this wrapper, if accepted, would not be implemented until Elixir drops support for OTP 26, which I believe is 1.19 at the earliest.)
  2. Put the burden of using :json on the user: make Jason an optional dependency and add JSON encoder/decoder options that default to using Jason if present or raise an error suggesting to add the dependency otherwise.
    • :decode_json options could be passed to the decoder function; it would be up to the user to implement them in terms of :json if they've overridden the default Jason decoder.
  3. Put the burden of using :json on Req: make Jason an optional dependency and provide encoder/decoder implementations in order of Jason > :json > raise an error.
    • Would have to decide what to do about :decode_json options. I don't think it's reasonable for a Req-provided :json implementation to accept every option that Jason does.
    • Would have to decide what to do about the differences between Jason and :json when it comes to struct encoding.

This ended up a bit longer than I anticipated, but hopefully is a decent jumping-off point.

zachallaun avatar Jul 16 '24 13:07 zachallaun