How should we handle JsonSerializer.DeserializeAsync nullable return type?

[0xced]

The System.Text.Json.JsonSerializer.DeserializeAsync<TValue> method returns a nullable type (TValue?).

The documentation says

Returns
ValueTask<TValue>
A TValue representation of the JSON value.

But the actual return type is ValueTask<TValue?> and the documentation forgets to mention that. So, what does that mean? How can a result be null instead of an exception being thrown during deserialization?

I'm currently throwing a JsonException but I think it's pretty bad because the exception message is rather useless.

var mediaInfo = await JsonSerializer.DeserializeAsync<MediaInfo>(stream, cancellationToken);
if (mediaInfo is null)
{
    throw new JsonException("Failed to deserialize the JSON stream as MediaInfo.");
}

How are we supposed to handle JsonSerializer.DeserializeAsync returning null?

[FiniteReality]

I honestly think it would be way more practical if Deserialize and co. only returned a nullable value if the input was nullable. Pretty much all of my Deserialize/DeserializeAsync calls have the same guard on them.

[huoyaoyuan]

So, what does that mean? How can a result be null instead of an exception being thrown during deserialization?

If you pass a root literal null (the json text is null without quotation), it should be deserialized as null.

Generally, you should always verify bad input. Sometimes it's correctly formed, but the content of fields are bad. Nulls can be handled in the verification, together with null fields.

[0xced]

I did not think about a root literal null! It makes sense but it would be worth documenting explicitly in the System.Text.Json.JsonSerializer.DeserializeAsync<TValue> documentation.