[API Proposal]: Add support for custom JSON deserialization error messages to System.Text.Json

[magyarandras]

Background and motivation

Currently, when the JsonSerializer can't convert a value to a specific type or encounters invalid/malformed JSON it throws a JsonException with a default message. For example, The JSON value could not be converted to System.DateTime. Path: $.Date | LineNumber: 1 | BytePositionInLine: 36.
The default message is useful, but there should be a feature that allows specifying custom error messages.

An attribute could be used for the purpose.

(There might be workarounds in some cases, for example creating custom JsonConverters and extending the JsonConverterAttribute to pass a message parameter works for properties, but it would be more convenient if the library could support this feature out of the box.)

This feature can be useful in many cases, for example, REST API clients can get more user-friendly or even localized JSON parsing error messages from the server.

For more details see my implementation: magyarandras@a0538d2

API Proposal

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

namespace System.Text.Json.Serialization
{

    /// <summary>
    /// Specifies a custom JSON serialization error message
    /// </summary>
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct | AttributeTargets.Property | AttributeTargets.Field, AllowMultiple = false)]
    public sealed class JsonSerializationErrorAttribute : JsonAttribute
    {
        /// <summary>
        /// The serialization error message.
        /// </summary>
        public string Message { get; }

        /// <summary>
        /// Initializes a new instance of <see cref="JsonSerializationErrorAttribute"/>.
        /// </summary>
        public JsonSerializationErrorAttribute(string message)
        {
            Message = message;
        }
    }

}

public abstract partial class JsonPropertyInfo
{
    public string ErrorMessage { get { throw null; } set { } }
}

API Usage

[JsonSerializationError("Invalid JSON! Path: {0} Line: {1} Byte position: {2}")]
public class Event
{
    [JsonSerializationError("Invalid event date! Path: {0} Line: {1} Byte position: {2}")]
    public DateTime EventDate { get; set; }
}

string jsonString = @"{
    ""EventDate"": ""Not a date""
}";
        
try
{
   JsonSerializer.Deserialize<Event>(jsonString);
}
catch(JsonException ex)
{
   //Should be "Invalid event date! Path: $.EventDate Line: 1 Byte position: 41"
   Console.WriteLine(ex.Message);
}

//Missing curly bracket
string invalidJsonString = @"{
    ""EventDate"": ""2022-10-05""
";

try
{
    JsonSerializer.Deserialize<Event>(invalidJsonString);
}
catch(JsonException ex)
{
   //Should be "Invalid JSON! Path: $ Line: 2 Byte position: 8"
   Console.WriteLine(ex.Message);
}

Alternative Designs

No response

Risks

No response

Tagging subscribers to this area: @dotnet/area-system-text-json, @gregsdennis
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

Currently, when the JsonSerializer can't convert a value to a specific type or encounters invalid/malformed JSON it throws a JsonException with a default message. For example, The JSON value could not be converted to System.DateTime. Path: $.Date | LineNumber: 1 | BytePositionInLine: 36.
The default message is useful, but there should be a feature that allows specifying custom error messages.

An attribute could be used for the purpose.

(There might be workarounds in some cases, for example creating custom JsonConverters and extending the JsonConverterAttribute to pass a message parameter works for properties, but it would be more convenient if the library could support this feature out of the box.)

This feature can be useful in many cases, for example, REST API clients can get more user-friendly or even localized JSON parsing error messages from the server.

For more details see my implementation: magyarandras@a0538d2

API Proposal

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

namespace System.Text.Json.Serialization
{

    /// <summary>
    /// Specifies a custom JSON serialization error message
    /// </summary>
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct | AttributeTargets.Property | AttributeTargets.Field, AllowMultiple = false)]
    public sealed class JsonSerializationErrorAttribute : JsonAttribute
    {
        /// <summary>
        /// The serialization error message.
        /// </summary>
        public string Message { get; }

        /// <summary>
        /// Initializes a new instance of <see cref="JsonSerializationErrorAttribute"/>.
        /// </summary>
        public JsonSerializationErrorAttribute(string message)
        {
            Message = message;
        }
    }

}

public abstract partial class JsonPropertyInfo
{
    public string ErrorMessage { get { throw null; } set { } }
}

API Usage

[JsonSerializationError("Invalid JSON! Path: {0} Line: {1} Byte position: {2}")]
public class Event
{
    [JsonSerializationError("Invalid event date! Path: {0} Line: {1} Byte position: {2}")]
    public DateTime EventDate { get; set; }
}

string jsonString = @"{
    ""EventDate"": ""Not a date""
}";
        
try
{
   JsonSerializer.Deserialize<Event>(jsonString);
}
catch(JsonException ex)
{
   //Should be "Invalid event date! Path: $.EventDate Line: 1 Byte position: 41"
   Console.WriteLine(ex.Message);
}

//Missing curly bracket
string invalidJsonString = @"{
    ""EventDate"": ""2022-10-05""
";

try
{
    JsonSerializer.Deserialize<Event>(invalidJsonString);
}
catch(JsonException ex)
{
   //Should be "Invalid JSON! Path: $ Line: 2 Byte position: 8"
   Console.WriteLine(ex.Message);
}

Alternative Designs

No response

Risks

No response

Author:	magyarandras
Assignees:	-
Labels:	api-suggestion, area-System.Text.Json
Milestone:	-

[Clockwork-Muse]

This feature can be useful in many cases, for example, REST API clients can get more user-friendly or even localized JSON parsing error messages from the server.

Not really. That's more dependent on the error specifications of the API ("when you cause an error, what does the JSON API return at all"), than the specific way it's deserialized.
This feature can help generate better errors for debugging purposes, but aren't going to automatically help with API issues. Also, this won't allow you to generate localized error messages: your server process should be running in the invariant locale (at the very least you have to parse JSON that way, since some number schemes conflict with it). Generally localized error messages, if any, are an application-layer concern; you'd catch the parse error and throw a custom error using the property name and other information.

[magyarandras]

@Clockwork-Muse While I agree that generating error messages for end users should belong to the application layer, I think it is hard to find an elegant way to produce non-general error messages (based on information in JsonException like Path) that are specific to the properties without an attribute like this.

[krwq]

I'll suggest different solution to this problem. Add specialized exception types to STJ with whatever members you'd find useful to throw good error message (i.e. Type, MemberName, JsonName whatever you think is suitable). Then in your code simply try..catch and write your own message. I don't think we have precedence anywhere in the framework for customized error messages the way it's proposed in this issue.

Also another thing to take a look at: possibly play around with TypeInfoResolver... Possibly you could wrap options.GetConverter(JsonPropertyInfo.PropertyType) with your own one which handles errors and assign it to JsonPropertyInfo.CustomConverter and create your own converter which handles the attribute (you can check custom attributes with JsonPropertyInfo.AttributeProvider; if there is no attribute then you do nothing). You'd need to experiment a bit to see if that would even solve your problem

[eiriktsarpalis]

Another issue with this proposal is that it assumes that serialization/deserialization has only one type of failure mode that can be user customizable. While we want to improve the quality of our error messages and provide users with ability to customize error messages for their types, I don't think this is the best way forward. I think writing a custom converter would be the prefered approach here.

[magyarandras]

@krwq @eiriktsarpalis Thank you for your feedback! I agree with you my proposal was not well thought out. I already have a solution that uses a custom JsonConverter and doesn't necessarily need the modification of STJ, as I mentioned before it only works for properties, but doesn't work when the JSON is invalid/malformed, however, it is not a problem because in the case of syntactically invalid JSON generic error messages are fine.

The only issue with it is that I can't optionally append data like path, and line position to the message, because they are not set yet when I catch the JsonException in the Read method of the JsonConverter.

using System;
using System.Text.Json;
using System.Text.Json.Serialization;


public class JsonConverterWithMessage<T> : JsonConverter<T>
{
    private string _message;

    public JsonConverterWithMessage(string message)
    {
        _message = message;
    }

    public override T? Read(
        ref Utf8JsonReader reader,
        Type typeToConvert,
        JsonSerializerOptions options)
    {
        try
        {
            return JsonSerializer.Deserialize<T>(ref reader, options);
        }
        catch (JsonException ex)
        {
            //ex.Path etc. not correctly set here
            throw new JsonException(_message);
        }

    }

    public override void Write(
        Utf8JsonWriter writer,
        T obj,
        JsonSerializerOptions options)
    {
        JsonSerializer.Serialize(writer, obj, options);
    }
}

[AttributeUsage(AttributeTargets.Property, AllowMultiple = false)]
public class JsonConverterWithMessageAttribute : JsonConverterAttribute
{
    private string _message;

    public JsonConverterWithMessageAttribute(string message)
    {
        this._message = message;
    }

    public override JsonConverter CreateConverter(Type typeToConvert)
    {
        var converterType = typeof(JsonConverterWithMessage<>).MakeGenericType(typeToConvert);
        return (JsonConverter)Activator.CreateInstance(converterType, _message)!;
    }
}


public class Event
{
    [JsonConverterWithMessage("Invalid event date!")]
    public DateTime EventDate { get; set; }

}

public class Program
{
    public static void Main()
    {
        string jsonString = @"{
			""EventDate"": ""Not a date"",
		}";

        try
        {
            Event? evt = JsonSerializer.Deserialize<Event>(jsonString);

            if (evt != null)
            {
                Console.WriteLine(evt.EventDate);
            }
        }
        catch (JsonException ex)
        {
            //Should be "Invalid event date!"
            Console.WriteLine(ex.Message);
        }
    }
}

How can this issue be solved? Is adding the exception data to the message with string.Format() in AddJsonExceptionInformation a bad idea?

string? message = ex._message;
if (!string.IsNullOrEmpty(message))
{
    ex.SetMessage(string.Format(message, path, lineNumber, bytePositionInLine));
}

My concern is that it might break people's existing codes in rare cases when they throw JsonException with a format string.
Is there any other way to do this?

[krwq]

@magyarandras so if I understand correctly you're seeing inner path relative to where converter called Serialize/Deserialize but because you don't know where you're at currently you cannot concat paths correctly? (neither there is way to pass in current path) If I understood that correctly then I'll recommend to create another issue with only that information so we can talk about this problem separately. Please create issue for each individual problem - it will be much easier to move the current state forward this way.

This issue has been marked needs-author-action and may be missing some important information.

This issue has been automatically marked no-recent-activity because it has not had any activity for 14 days. It will be closed if no further activity occurs within 14 more days. Any new comment (by anyone, not necessarily the author) will remove no-recent-activity.