req
req copied to clipboard
`json`: Support optional use of `:json` in OTP 27+
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 tovalue |> :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 likekeys: :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 implementJason.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:
- 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 onJason
. (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.) - Put the burden of using
:json
on the user: make Jason an optional dependency and add JSON encoder/decoder options that default to usingJason
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.
-
- Put the burden of using
:json
on Req: make Jason an optional dependency and provide encoder/decoder implementations in order ofJason > :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 thatJason
does. - Would have to decide what to do about the differences between
Jason
and:json
when it comes to struct encoding.
- Would have to decide what to do about
This ended up a bit longer than I anticipated, but hopefully is a decent jumping-off point.