98

I've been working with JSON.net for a while. I have written both custom converters and custom contract resolvers (generally from modifying examples on S.O. and the Newtonsoft website), and they work fine.

The challenge is, other than examples, I see little explanation as to when I should use one or the other (or both) for processing. Through my own experience, I've basically determined that contract resolvers are simpler, so if I can do what I need with them, I go that way; otherwise, I use custom JsonConverters. But, I further know both are sometimes used together, so the concepts get further opaque.

Questions:

  1. Is there a source that distinguishes when to user one vs. the other? I find the Newtonsoft documentation unclear as to how the two are differentiated or when to use one or the other.
  2. What is the pipeline of ordering between the two?

1 Answer 1

256
+100

Great question. I haven't seen a clear piece of documentation that says when you should prefer to write a custom ContractResolver or a custom JsonConverter to solve a particular type of problem. They really do different things, but there is some overlap between what kinds of problems can be solved by each. I've written a fair number of each while answering questions on StackOverflow, so the picture has become a little more clear to me over time. Below is my take on it.

ContractResolver

A contract resolver is always used by Json.Net, and governs serialization / deserialization behavior at a broad level. If there is not a custom resolver provided in the settings, then the DefaultContractResolver is used. The resolver is responsible for determining:

  • what contract each type has (i.e. is it a primitive, array/list, dictionary, dynamic, JObject, plain old object, etc.);
  • what properties are on the type (if any) and what are their names, types and accessibility;
  • what attributes have been applied (e.g. [JsonProperty], [JsonIgnore], [JsonConverter], etc.), and
  • how those attributes should affect the (de)serialization of each property (or class).

Generally speaking, if you want to customize some aspect of serialization or deserialization across a wide range of classes, you will probably need to use a ContractResolver to do it. Here are some examples of things you can customize using a ContractResolver:

JsonConverter

In contrast to a ContractResolver, the focus of a JsonConverter is more narrow: it is really intended to handle serialization or deserialization for a single type or a small subset of related types. Also, it works at a lower level than a resolver does. When a converter is given responsibility for a type, it has complete control over how the JSON is read or written for that type: it directly uses JsonReader and JsonWriter classes to do its job. In other words, it can change the shape of the JSON for that type. At the same time, a converter is decoupled from the "big picture" and does not have access to contextual information such as the parent of the object being (de)serialized or the property attributes that were used with it. Here are some examples of problems you can solve with a JsonConverter:

5
  • 4
    Wow that's a very thorough answer... I would add a fews things after a week or so of testing a lot of aspects.
    – frigon
    Commented Dec 17, 2016 at 22:16
  • 2
    Exactly the clarifications and resources I needed. Thanks for all the hard work on this. Commented Jun 29, 2017 at 15:08
  • 1
    i know "thanks" comments are not really wanted, but this answer deserves one: thanks, especially for all the links!
    – mike
    Commented May 8, 2018 at 22:21
  • Hi Brian. I was wondering if I could use one of these techniques to avoid having to decorate my Json. I am currently deserialising a pretty complex objects and I have to pollute my Jsons with things such as $type: "System.Collections.Generic.List`1[[ClassName, Namespace]], mscorlib" Commented Apr 27, 2021 at 7:35
  • @progLearner Yes, almost certainly. You're probably looking for something like Deserializing polymorphic json classes without type information using json.net. If you need more specific help than that, please post a new question. Commented Apr 27, 2021 at 16:19

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.