Newtonsoft.Json Polymorphic Serialization Fix with XmlElement

by

Summary

Problem: When serializing XSD‑generated classes with Newtonsoft.Json, a polymorphic property (object Item) is always emitted with the property name Item. In the original XML the element name changes dynamically (e.g., TransmitRequest, ReportRequest) based on the concrete type indicated by XmlElementAttribute. The goal is to make JSON output use the attribute‑defined name that matches the runtime type of Item.

Solution: Implement a custom JsonConverter (or a ContractResolver that delegates to a converter) that:

  1. Inspects the runtime type of the value being written.
  2. Looks up the XmlElementAttribute (or a custom attribute) on the declaring property to find the element name that matches the concrete type.
  3. Writes a single‑property JSON object whose property name is that element name and whose value is the serialized payload of the concrete object.

The converter is applied only to the Item property, leaving the rest of the contract untouched.

Root Cause

  • Newtonsoft.Json uses the CLR property name (Item) as the JSON property name unless overridden by JsonPropertyAttribute or a contract resolver.
  • XmlElementAttribute is XML‑specific; Json.NET does not read it for naming.
  • The object type provides no compile‑time information, so the default contract resolver cannot infer the concrete type to pick the correct XML element name.

Why This Happens in Real Systems

  • Code generation from XSD creates polymorphic members that rely on XML metadata (XmlElementAttribute) for element names.
  • Teams often reuse the same classes for both XML and JSON APIs without adding JSON‑specific metadata.
  • The default JSON contract resolver ignores XML attributes, leading to generic property names like Item, Value, or Any.

Real-World Impact

  • Interoperability bugs: Clients expecting { "TransmitRequest": { … } } receive { "Item": { … } }, causing schema validation failures.
  • Increased maintenance: Developers write ad‑hoc mapping layers or manual DTOs to work around the mismatch.
  • Hidden runtime errors: Deserialization fails silently when the consumer looks for the dynamic property name.
  • Performance penalty: Re‑serializing with custom wrappers or reflection‑heavy workarounds adds overhead in high‑throughput services.

Example or Code (if necessary and relevant)

public class XmlElementNameConverter : JsonConverter
{
    public override bool CanConvert(Type objectType) => true;

    public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer)
    {
        if (value == null) { writer.WriteNull(); return; }

        // 1. Get the runtime type (e.g., TransmitRequestType)
        Type actualType = value.GetType();

        // 2. Find the XmlElementAttribute that matches this type
        var propInfo = typeof(ParentClass).GetProperty(nameof(ParentClass.Item));
        var xmlAttrs = propInfo.GetCustomAttributes(typeof(XmlElementAttribute), false)
                              .Cast();

        string elementName = xmlAttrs
            .FirstOrDefault(a => a.Type == actualType)?
            .ElementName ?? actualType.Name;

        // 3. Write { "elementName": { …payload… } }
        writer.WriteStartObject();
        writer.WritePropertyName(elementName);
        serializer.Serialize(writer, value);
        writer.WriteEndObject();
    }

    public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer)
    {
        // Deserialization logic (mirror of WriteJson) omitted for brevity
        throw new NotImplementedException();
    }
}

Apply the converter:

public class ParentClass
{
    [JsonConverter(typeof(XmlElementNameConverter))]
    [XmlElement("ReportRequest", typeof(ReportRequestType))]
    [XmlElement("StatusRequest", typeof(StatusRequestType))]
    [XmlElement("TransmitRequest", typeof(TransmitRequestType))]
    public object Item { get; set; }
}

Only the converter code block is shown; all explanations remain outside the fences.

How Senior Engineers Fix It

  • Leverage existing XML metadata: Scan XmlElementAttribute at runtime instead of duplicating naming information in a custom attribute.
  • Scope the converter: Attach it directly to the polymorphic property to avoid affecting unrelated contracts.
  • Cache reflection results: Store a dictionary Type → elementName per declaring property to eliminate per‑serialization reflection overhead.
  • Provide symmetric deserialization: Implement ReadJson to detect the single property name and instantiate the appropriate concrete type.
  • Write unit tests: Verify round‑trip serialization for each possible concrete type, ensuring the JSON name matches the XML element name.

Why Juniors Miss It

  • Assume one contract fits all: They often expect Json.NET to honor any attribute automatically, not realizing the separation between XML and JSON metadata.
  • Over‑rely on default behavior: They may try to solve the problem with JsonProperty or DefaultContractResolver without realizing those APIs lack access to the runtime value needed to pick the correct name.
  • Skip reflection caching: A naive implementation that reflects on every serialization call can cause performance regressions, which junior engineers may overlook.
  • Neglect deserialization symmetry: Focusing only on the write path leads to mismatched round‑trip behavior, a common pitfall for less‑experienced developers.

Leave a Comment